Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
indigo_s_restful_urls [2015/07/13 15:32] – jayindigo_s_restful_urls [2026/04/07 18:27] (current) – external edit 127.0.0.1
Line 1: Line 1:
 +====== Indigo REST API ======
 +<color red>**//NOTE//**</color> : this API was **deprecated in Indigo v2022.2**.
 +
 +These REST semantics are loosely based [[http://microformats.org/wiki/rest/urls|RoR's use of RESTful URLs.]]
 +
 +===== Devices Access =====
 +Examples to get HTML, JSON (new in Indigo 6), XML, and TXT versions of the device list:
 +<code>
 +http://127.0.0.1:8176/devices/
 +http://127.0.0.1:8176/devices.json/
 +http://127.0.0.1:8176/devices.xml/
 +http://127.0.0.1:8176/devices.txt/
 +</code>
 +
 +Examples to get HTML, XML, and TXT versions of device "office-lamp":
 +<code>
 +http://127.0.0.1:8176/devices/office-lamp.html
 +http://127.0.0.1:8176/devices/office-lamp.json
 +http://127.0.0.1:8176/devices/office-lamp.xml
 +http://127.0.0.1:8176/devices/office-lamp.txt
 +</code>
 +
 +Example of editing using HTML form to modify office-lamp editable properties; Form submit will do a virtual PUT to update the properties:
 +<code>
 +http://127.0.0.1:8176/devices/office-lamp/edit
 +</code>
 +
 +Example use of curl and virtual HTTP PUT call to change brightness to 27; HTTP result is a 303 redirect back to the device resource after the update is complete:
 +<code>
 +curl -X PUT -d brightness=27 http://127.0.0.1:8176/devices/office-lamp
 +http://127.0.0.1:8176/devices/office-lamp?brightness=27&_method=put
 +</code>
 +
 +Example use of curl and virtual HTTP PUT call to change office-lamp's isOn to False and True:
 +<code>
 +curl -X PUT -d isOn=0 http://127.0.0.1:8176/devices/office-lamp
 +curl -X PUT -d isOn=1 http://127.0.0.1:8176/devices/office-lamp
 +http://127.0.0.1:8176/devices/office-lamp?isOn=0&_method=put
 +http://127.0.0.1:8176/devices/office-lamp?isOn=1&_method=put
 +</code>
 +
 +Example use of curl and virtual HTTP PUT call to toggle office-lamp's state:
 +<code>
 +curl -X PUT -d toggle=1 http://127.0.0.1:8176/devices/office-lamp
 +http://127.0.0.1:8176/devices/office-lamp?toggle=1&_method=put
 +</code>
 +
 +Example use of curl and virtual HTTP PUT call to change speedIndex to 0 (off), 3 (high), then decrease back to 0 (off):
 +<code>
 +curl -X PUT -d speedIndex=0 http://127.0.0.1:8176/devices/office-ceiling-fan
 +curl -X PUT -d speedIndex=3 http://127.0.0.1:8176/devices/office-ceiling-fan
 +curl -X PUT -d speedIndex=dn http://127.0.0.1:8176/devices/office-ceiling-fan
 +curl -X PUT -d speedIndex=dn http://127.0.0.1:8176/devices/office-ceiling-fan
 +curl -X PUT -d speedIndex=dn http://127.0.0.1:8176/devices/office-ceiling-fan
 +http://127.0.0.1:8176/devices/office-ceiling-fan?speedIndex=0&_method=put
 +http://127.0.0.1:8176/devices/office-ceiling-fan?speedIndex=3&_method=put
 +http://127.0.0.1:8176/devices/office-ceiling-fan?speedIndex=dn&_method=put
 +http://127.0.0.1:8176/devices/office-ceiling-fan?speedIndex=dn&_method=put
 +http://127.0.0.1:8176/devices/office-ceiling-fan?speedIndex=dn&_method=put
 +</code>
 +
 +Example use of curl and virtual HTTP PUT call to change device "irrmaster-pro" active sprinkler zone to 3 and all off:
 +<code>
 +curl -X PUT -d activeZone=3 http://127.0.0.1:8176/devices/irrmaster-pro
 +curl -X PUT -d activeZone=0 http://127.0.0.1:8176/devices/irrmaster-pro
 +http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=3&_method=put
 +http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=0&_method=put
 +</code>
 +
 +Example use of curl and virtual HTTP PUT call to change device "irrmaster-pro" sprinkler mode:
 +<code>
 +curl -X PUT -d activeZone=stop http://127.0.0.1:8176/devices/irrmaster-pro
 +curl -X PUT -d activeZone=run http://127.0.0.1:8176/devices/irrmaster-pro
 +curl -X PUT -d activeZone=pause http://127.0.0.1:8176/devices/irrmaster-pro
 +curl -X PUT -d activeZone=resume http://127.0.0.1:8176/devices/irrmaster-pro
 +curl -X PUT -d activeZone=next http://127.0.0.1:8176/devices/irrmaster-pro
 +curl -X PUT -d activeZone=prev http://127.0.0.1:8176/devices/irrmaster-pro
 +http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=stop&_method=put
 +http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=run&_method=put
 +http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=pause&_method=put
 +http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=resume&_method=put
 +http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=next&_method=put
 +http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=prev&_method=put
 +</code>
 +
 +Example use of curl and virtual HTTP PUT call to change device "thermostat" heat and cool setpoints:
 +<code>
 +curl -X PUT -d setpointCool=68 -d setpointHeat=84 http://127.0.0.1:8176/devices/thermostat
 +curl -X PUT -d setpointCool=72 -d setpointHeat=78 http://127.0.0.1:8176/devices/thermostat
 +curl -X PUT -d setpointCool=up -d setpointHeat=up http://127.0.0.1:8176/devices/thermostat
 +curl -X PUT -d setpointCool=dn -d setpointHeat=dn http://127.0.0.1:8176/devices/thermostat
 +http://127.0.0.1:8176/devices/thermostat?_method=put&setpointCool=68&setpointHeat=84
 +http://127.0.0.1:8176/devices/thermostat?_method=put&setpointCool=72&setpointHeat=78
 +http://127.0.0.1:8176/devices/thermostat?_method=put&setpointCool=up&setpointHeat=up
 +http://127.0.0.1:8176/devices/thermostat?_method=put&setpointCool=dn&setpointHeat=dn
 +</code>
 +
 +Example use of curl and virtual HTTP PUT call to change device "thermostat" hvac mode to "cool on" and "auto on":
 +<code>
 +curl -X PUT -d hvacCurrentMode="cool on" http://127.0.0.1:8176/devices/thermostat
 +curl -X PUT -d hvacCurrentMode="auto on" http://127.0.0.1:8176/devices/thermostat
 +http://127.0.0.1:8176/devices/thermostat?_method=put&hvacCurrentMode=cool%20on
 +http://127.0.0.1:8176/devices/thermostat?_method=put&hvacCurrentMode=auto%20on
 +</code>
 +
 +Example use of curl and virtual HTTP PUT call to change device "thermostat" hvac fan mode to "always on" and "auto on":
 +<code>
 +curl -X PUT -d hvacFanMode="always on" http://127.0.0.1:8176/devices/thermostat
 +curl -X PUT -d hvacFanMode="auto on" http://127.0.0.1:8176/devices/thermostat
 +http://127.0.0.1:8176/devices/thermostat?_method=put&hvacFanMode=always%20on
 +http://127.0.0.1:8176/devices/thermostat?_method=put&hvacFanMode=auto%20on
 +</code>
 +
 +Example use of curl and virtual HTTP PUT call to change binary output state of an EZIO module device "garage-io":
 +<code>
 +curl -X PUT -d outputBinaryStates="0,0,0,0,1,1,1,1" http://127.0.0.1:8176/devices/garage-io
 +curl -X PUT -d outputBinaryStates="1,0,1,0,0,0,0,0" http://127.0.0.1:8176/devices/garage-io
 +curl -X PUT -d outputBinaryStates="set4" http://127.0.0.1:8176/devices/garage-io
 +curl -X PUT -d outputBinaryStates="clear4" http://127.0.0.1:8176/devices/garage-io
 +http://127.0.0.1:8176/devices/garage-io?_method=put&outputBinaryStates=0,0,0,0,1,1,1,1
 +http://127.0.0.1:8176/devices/garage-io?_method=put&outputBinaryStates=1,0,1,0,0,0,0,0
 +http://127.0.0.1:8176/devices/garage-io?_method=put&outputBinaryStates=set4
 +http://127.0.0.1:8176/devices/garage-io?_method=put&outputBinaryStates=clear4
 +</code>
 +
 +===== Variable Access =====
 +Examples to get HTML, JSON (new in Indigo 6), XML, and TXT versions of the variable list:
 +<code>
 +http://127.0.0.1:8176/variables/
 +http://127.0.0.1:8176/variables.json/
 +http://127.0.0.1:8176/variables.xml/
 +http://127.0.0.1:8176/variables.txt/
 +</code>
 +
 +Examples to get HTML, JSON (new in Indigo 6), XML, and TXT versions of variable "sprinklerDurationMultiplier":
 +<code>
 +http://127.0.0.1:8176/variables/sprinklerDurationMultiplier.html
 +http://127.0.0.1:8176/variables/sprinklerDurationMultiplier.json
 +http://127.0.0.1:8176/variables/sprinklerDurationMultiplier.xml
 +http://127.0.0.1:8176/variables/sprinklerDurationMultiplier.txt
 +</code>
 +
 +Example use of curl and virtual HTTP PUT call to change variable "sprinklerDurationMultiplier" value to 1.23; HTTP result is a 303 redirect back to the variable resource after the update is complete:
 +<code>
 +curl -X PUT -d value=1.23 http://127.0.0.1:8176/variables/sprinklerDurationMultiplier
 +http://127.0.0.1:8176/variables/sprinklerDurationMultiplier?_method=put&value=1.23
 +</code>
 +
 +And, while not exactly RESTful, here's the URL you can use in your custom control pages to link to an editor page for a variable (select "Link to External URL" on the "Client action" popup and insert the following):
 +
 +<code>/editvarpage?name=SOME_VARIABLE_NAME&redirectPage=RETURN_PAGE_NAME</code>
 +
 +That replaces the variable plugin that's in the user contribution library.
 +
 +===== Action Group Access and Execution =====
 +Examples to get HTML, JSON (new in Indigo 6), XML, and TXT versions of the action group list:
 +<code>
 +http://127.0.0.1:8176/actions/
 +http://127.0.0.1:8176/actions.json/
 +http://127.0.0.1:8176/actions.xml/
 +http://127.0.0.1:8176/actions.txt/
 +</code>
 +
 +Examples to get HTML, JSON (new in Indigo 6), XML, and TXT versions of action group "cooking scene":
 +<code>
 +http://127.0.0.1:8176/actions/cooking%20scene.html
 +http://127.0.0.1:8176/actions/cooking%20scene.json
 +http://127.0.0.1:8176/actions/cooking%20scene.xml
 +http://127.0.0.1:8176/actions/cooking%20scene.txt
 +</code>
 +
 +Example use of curl and virtual HTTP execute call to execute action group "party scene":
 +<code>
 +curl -X EXECUTE http://127.0.0.1:8176/actions/party%20scene
 +http://127.0.0.1:8176/actions/party%20scene?_method=execute
 +</code>
 +
 +===== INSTEON Links Retrieval =====
 +Example to get XML version (HTML, JSON and TXT not available) of the INSTEON links:
 +<code>
 +http://127.0.0.1:8176/insteonlinks/
 +</code>
 +
 +Example to get XML INSTEON links for device "office-lamp":
 +<code>
 +http://127.0.0.1:8176/insteonlinks/office-lamp
 +</code>
 +
 +Example to get XML INSTEON links for the PowerLinc:
 +<code>
 +http://127.0.0.1:8176/insteonlinks/PowerLinc%20Interface
 +</code>
 +
 +===== Authentication =====
 +As of v2021.1, Indigo now supports both basic and digest HTTP authentication simultaneously, and offers a new API key feature for use with the API. To use either of the HTTP authentication methods, you must have a username/password set in the Start Local Server dialog.
 +
 +===== HTTP Authentication =====
 +**HTTP Digest** authentication is the default authentication method for the REST API. To use it in the curl examples above, you can specify your authentication like this:
 +
 +<code>curl -u user:password --digest [other options here]</code>
 +
 +In Python, we recommend using the [[https://docs.python-requests.org/en/master/|requests library]] (included with Indigo and available to Indigo Python scripts):
 +
 +<code>import requests
 +from requests.auth import HTTPDigestAuth
 +reply = requests.get('https://myreflector.indigodomo.net/', auth=HTTPDigestAuth('username', 'password'))
 +</code>
 +
 +Of course, you would use the full REST URL. That will allow your scripts to successfully authenticate and execute against a protected server.
 +
 +If you have **HTTP Basic** authentication enabled in the Start Local Server dialog, you can pass the username and password on the URL itself (note that this is less secure and should only be used on HTTPS connections since the password is sent in clear text on non-HTTPS URLs):
 +
 +https://username:[email protected]/
 +
 +We don't enable Basic auth by default because it is less secure than Digest auth, but we make it available when you have no other option to integrate from an outside source.
 +
 +===== API Key =====
 +In Indigo 2021.1 or later, you can use an even more secure API token to authenticate your REST requests.
 +
 +<color blue>**Note**</color>: To use API Keys with the REST API, you must have an active Indigo Up-to-Date subscription.
 +
 +To use keys to authenticate REST calls, you must first generate an API Key in your Indigo Account. Log in and select the Authorizations item in the navigation menu on the left. This will show you a page that looks something like this:
 +
 +{{:authorizations.png?nolink|Authorizations Image}}
 +
 +The lower section of the page shows your API Keys. You can generate a new key by selecting your license from the popup at the bottom and clicking the Add API Key button. This will generate a key that is valid on the license specified (most users just have a single license, but some have multiple).
 +
 +Next, when you make a call to the REST API, you will include the Authorization header with the value of 'Bearer API_KEY_HERE'. In curl:
 +
 +<code>curl -H "Authorization: Bearer API_KEY_HERE" [other options here]</code>
 +
 +In Python:
 +
 +<code>import requests
 +my_headers = {"Authorization": "Bearer API_KEY_HERE"}
 +reply = requests.get('https://myreflector.indigodomo.net/', headers=my_headers)
 +</code>
 +
 +Again, you would use the full REST URL rather than just the host.
 +
 +===== AppleScript & the RESTful API =====
 +To work around the Mac OS X "application isn't running" bug (error -600) that seems to be getting worse with each OS release, you can communicate between an external AppleScript (or app that runs AppleScripts) by using the curl command in a **do shell script** AppleScript call with the commands above to set (and get) information from the Indigo server.
 +
 +For example, here's a simple AppleScript that will turn an Indigo device ON and then OFF:
 +
 +<code>
 +set indigoServerIPandPort to "192.168.1.123:8176"
 +set indigoServerUsername to "username here"
 +set indigoServerPassword to "password here"
 +set devName to "office%20lamp" -- note spaces have to escaped by substituting with %20
 +set turnOffCommand to "curl -u " & indigoServerUsername & ":" & indigoServerPassword & " --digest -X PUT -d isOn=0 http://" & indigoServerIPandPort & "/devices/" & devName
 +set turnOnCommand to "curl -u " & indigoServerUsername & ":" & indigoServerPassword & " --digest -X PUT -d isOn=1 http://" & indigoServerIPandPort & "/devices/" & devName
 +do shell script turnOnCommand
 +do shell script turnOffCommand
 +</code>
 +
 +And here's a simple AppleScript that will set the value of an Indigo variable:
 +
 +<code>
 +set indigoServerIPandPort to "192.168.1.123:8176"
 +set indigoServerUsername to "username here"
 +set indigoServerPassword to "password here"
 +set varName to "someVariable"
 +set varValue to "hello"
 +set commandString to "curl -u " & indigoServerUsername & ":" & indigoServerPassword & " --digest -X PUT -d value=varValue http://" & indigoServerIPandPort & "/variables/" & varName
 +do shell script commandString
 +</code>
 +
 +Here's an example of getting a variable value:
 +
 +<code>
 +set varValueJson to do shell script "curl -u username:password --digest http://127.0.0.1:8176/variables/someVariable.json"
 +
 +tell application "JSON Helper"
 + set varValueRecord to read JSON from varValueJson
 + set varValue to value of varValueRecord
 +end tell
 +</code>
 +
 +Note, to use this script you need the Mac App called [[https://itunes.apple.com/WebObjects/MZStore.woa/wa/viewSoftware?id=453114608&mt=12 |JSON Helper]], which is free from the Mac App Store. This free app does a fantastic job of converting JSON formatted data into AppleScript native data types (like lists and records).
 +
 +This approach has the advantage of running from any Mac anywhere, whether on the same Mac as your server, another Mac on your local network, or a Mac somewhere out on the internet (use your reflector URL if you're doing the latter).
 +
 +You can also have AppleScript directly communicate with Indigo's python scripting engine [[https://github.com/IndigoDomotics/indigo-basic-applescript-control|as shown here]]. That is a slower technique but doesn't use Indigo's Web server and thus doesn't need the username or password embedded in the script.