RESTful API

HomeKit Bridge RESTFul API

The API has been designed for just one client: the Homebridge script. While this API could be used by other plugins, it is not designed for that and devs are ground-up rewriting the entire web server and API system in Indigo so using this for anything other than HomeKit Bridge doesn't really make sense. What follows here are the methods for the HomeKit Bridge RESTFul API.

---

Overview

This RESTFul implementation is not based on published standards and is completely utilitarian in nature. In general the commands are comprised of the following query parameters.

• cmd: What you want the API to do
• serverId: the Indigo device ID for the server (passed in the config.json file for Homebridge)
• objId: The Indigo ID for the item being controlled (Device, Action Group, Variable, etc)
• jkey: The serialized unique key given to each device added to a server

There may be additional query parameters for specific commands. All RESTFul queries are GET queries. You'll find the port for the server located in the config.json file as apiPort and you should use 127.0.0.1 as the IP address as the plugin will NOT support remote servers at this point.

---

Importance Of Server ID

Every RESTful query requires a serverId field because the plugin permits the user to assign an object to multiple servers and with that ability means they can also have different definitions for each instance of the object. On one server it may be a lightbulb while on another it could be a switch. While this situation is likely rare it is important to always query the object for the server it is attached to so that the proper definition is retrieved. This is why all URL fields always include the serverId with it.

---

Returned JSON Data

In each object detail there will be a URL parameter that gives you the entire prefix of where you need to go. All you need to do from that URL is give it a cmd to execute and whatever parameters are also required for that command.

For instance, if your Indigo server were at 10.1.200.3 and you went to the following URL for a device that you know is mapped to HomeBridge:

http://10.1.200.3:8558/HomeKit?cmd=getInfo&objId=1010303036&serverId=1794022133

You would get the following:

[
	{
		"versByte": "", 
		"name": "Basement Bar", 
		"hkservice": "Switch", 
		"url": "/HomeKit?objId=1010303036&serverId=1794022133&jkey=7f6ab27d7fd8b5a45e48ad0fa63c5e4642b298e95e11d89ff8d0156b54aadbb1", 
		"hkcharacteristics": [
			{
				"readonly": false, 
				"name": "On", 
				"value": false, 
				"notify": false
			}
		], 
		"object": "Device", 
		"alias": "Bar", 
		"deviceId": 1010303036, 
		"action": [
			"On"
		], 
		"type": "SwitchLinc Dimmer", 
		"id": "7f6ab27d7fd8b5a45e48ad0fa63c5e4642b298e95e11d89ff8d0156b54aadbb1"
	}
]

You can see from the returned JSON data the following information:

• name: The full Indigo name for the device
• hkservice: The HomeKit device service that this device will be mapped to
• url: The callback URL for all communication between HomeKit and Indigo via the RESTful API
• hkcharacteristics: Each service characteristic and the value of it for HomeKit
• object: The object type for Indigo (i.e., Device, Action Group, Variable, etc)
• alias: The name that HomeKit will use to reference this device and that will be seen in the UI
• action: Available characteristic actions that can be taken on the object
• deviceId: The Indigo object ID associated with the item
• id: The unique serialized key given to the object
• type: The model that HomeKit will display
• versBye: The firmware that HomeKit will display

---

deviceList

Retrieves a list of all devices for HomeKit that Indigo is publishing, including all of the parameters you would get if you queried an object individually. This allows for a single call to bring in all the data needed to populate all of HomeKit without any further queries.

The command is:

 http://[INDIGO_IP]:[API_PORT]/HomeKit?cmd=deviceList&serverId=[INDIGO_ID_FOR_HK_SERVER]

• INDIGO_IP: IP address for the Indigo server, derived from the config.json
• API_PORT: Port assigned to the web server running the RESTful API, derived from plugin preferences
• INDIGO_ID_FOR_HK_SERVER: The object ID assigned by Indigo for the plugin's HomeKit Bridge Server that this device is included in. This is important because it is possible for one device to be included in multiple servers.

EXAMPLE

 http://10.1.200.3:8558/HomeKit?cmd=deviceList&serverId=1794022133

---

getInfo

Retrieves all the information about any given object being used as a HomeKit device.

The command is:

 http://[INDIGO_IP]:[API_PORT]/HomeKit?cmd= getInfo&objId=[INDIGO_ID_FOR_OBJECT]&serverId=[INDIGO_ID_FOR_HK_SERVER]&jkey=[UNIQUE_SERIALIZED_KEY]

• INDIGO_IP: IP address for the Indigo server, derived from the config.json
• API_PORT: Port assigned to the web server running the RESTful API, derived from plugin preferences
• INDIGO_ID_FOR_OBJECT: The Indigo ID for the object being queried
• INDIGO_ID_FOR_HK_SERVER: The object ID assigned by Indigo for the plugin's HomeKit Bridge Server that this device is included in. This is important because it is possible for one device to be included in multiple servers.
• UNIQUE_SERIALIZED_KEY: The unique serialized key given to the object

EXAMPLE

 http://10.1.200.3:8558/HomeKit?cmd=getInfo&objId=1010303036&serverId=1794022133&jkey=7f6ab27d7fd8b5a45e48ad0fa63c5e4642b298e95e11d89ff8d0156b54aadbb1

---

setCharacteristic

Updates Indigo to reflect any change made to a HomeKit device.

The command is:

 http://[INDIGO_IP]:[API_PORT]/HomeKit?cmd= setCharacteristic&objId=[INDIGO_ID_FOR_OBJECT]&serverId=[INDIGO_ID_FOR_HK_SERVER]&jkey=[UNIQUE_SERIALIZED_KEY]&[CHARACTERISTIC]=[VALUE]...&[CHARACTERISTIC]=[VALUE]

• INDIGO_IP: IP address for the Indigo server, derived from the config.json
• API_PORT: Port assigned to the web server running the RESTful API, derived from plugin preferences
• INDIGO_ID_FOR_OBJECT: The Indigo ID for the object being queried
• INDIGO_ID_FOR_HK_SERVER: The object ID assigned by Indigo for the plugin's HomeKit Bridge Server that this device is included in. This is important because it is possible for one device to be included in multiple servers.
• CHARACTERISTIC=VALUE PAIRS: For each characteristic you are modifying, add an additional query parameter. It's OK that these are passed as strings because the plugin will translate that to the proper Indigo value for that characteristic
• UNIQUE_SERIALIZED_KEY: The unique serialized key given to the object

EXAMPLE

 http://10.1.200.3:8558/HomeKit?cmd=setCharacteristic&objId=1010303036&serverId=1794022133&jkey=7f6ab27d7fd8b5a45e48ad0fa63c5e4642b298e95e11d89ff8d0156b54aadbb1&On=false&Brightness=0