Indigo RESTful Overview

These RESTful semantics are loosely based 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:

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/

Examples to get HTML, XML, and TXT versions of device “office-lamp”:

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

Example of editing using HTML form to modify office-lamp editable properties; Form submit will do a virtual PUT to update the properties:

http://127.0.0.1:8176/devices/office-lamp/edit

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:

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

Example use of curl and virtual HTTP PUT call to change office-lamp's isOn to False and True:

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

Example use of curl and virtual HTTP PUT call to toggle office-lamp's state:

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

Example use of curl and virtual HTTP PUT call to change speedIndex to 0 (off), 3 (high), then decrease back to 0 (off):

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

Example use of curl and virtual HTTP PUT call to change device “irrmaster-pro” active sprinkler zone to 3 and all off:

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

Example use of curl and virtual HTTP PUT call to change device “irrmaster-pro” sprinkler mode:

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

Example use of curl and virtual HTTP PUT call to change device “thermostat” heat and cool setpoints:

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

Example use of curl and virtual HTTP PUT call to change device “thermostat” hvac mode to “cool on” and “auto on”:

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

Example use of curl and virtual HTTP PUT call to change device “thermostat” hvac fan mode to “always on” and “auto on”:

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

Example use of curl and virtual HTTP PUT call to change binary output state of an EZIO module device “garage-io”:

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

Variable Access

Examples to get HTML, JSON (new in Indigo 6), XML, and TXT versions of the variable list:

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/

Examples to get HTML, JSON (new in Indigo 6), XML, and TXT versions of variable “sprinklerDurationMultiplier”:

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

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:

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

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):

/editvarpage?name=SOME_VARIABLE_NAME&redirectPage=RETURN_PAGE_NAME

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:

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/

Examples to get HTML, JSON (new in Indigo 6), XML, and TXT versions of action group “cooking scene”:

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

Example use of curl and virtual HTTP execute call to execute action group “party scene”:

curl -X EXECUTE http://127.0.0.1:8176/actions/party%20scene
http://127.0.0.1:8176/actions/party%20scene?_method=execute

INSTEON Links Retrieval

Example to get XML version (HTML, JSON and TXT not available) of the INSTEON links:

http://127.0.0.1:8176/insteonlinks/

Example to get XML INSTEON links for device “office-lamp”:

http://127.0.0.1:8176/insteonlinks/office-lamp

Example to get XML INSTEON links for the PowerLinc:

http://127.0.0.1:8176/insteonlinks/PowerLinc%20Interface

Authentication

Indigo uses digest authentication when you have a username/password set in the Start Local Server dialog. In the curl examples above, you can specify your authentication like this:

curl -u user:password --digest [other options here]

That will allow your scripts to successfully authenticate and execute against a protected server.

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 script that will set the value of an Indigo variable:

set someValue to "hello"
set commandString to "curl -u username:password --digest -X PUT -d value=" & someValue & " http://127.0.0.1:8176/variables/someVariable"
do shell script commandString

Here's an example of getting a variable value:

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

Note, to use this script you need the Mac App called 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).

indigo_s_restful_urls.txt · Last modified: 2015/07/13 15:45 by jay
 

© 2015 Perceptive Automation, LLC. · Privacy