Chapter 11. The HTTP API interface

SwitchThat One provides a powerful API that allows you to access and control your devices using simple RESTful HTTP requests. You could use the One API to integrate SwitchThat One with other systems, such as a Voice recognition module, or perhaps write UNIX shell scripts to control or automate your devices.

11.1. API authentication

The One API is secured using basic access HTTP authentication.

If you haven’t already done so, you’ll need to create an API user, specifying the username & password you’ll use in your API requests. The process of creating an API user is described in Section 8.6.1, “Adding an API User”.

11.2. Making API requests

All API requests are made with a URL of the form: http://one-hub.local/api/type/name_or_id/action

where:

  • one-hub.local needs to be replaced by the name or IP address of your One Hub. We will use one-hub.local in this document to refer to the One Hub

  • type can be one of 'device', 'shortcut', or 'room'

  • The name_or_id will be either the name or id of a thing in your system, of the type you have specified. Names are case insensitive.

    If you want to use a name that has spaces (or other characters that are reserved in URLs), then they must be ‘encoded’. e.g. “my light” would become “my%20light” or “my+light”. See Wikipedia for more information.

  • action will be one of the Actions listed in the table in Appendix B, HTTP API Reference

You would get the current state of a device with a HTTP GET request, and you would use a HTTP POST request to update the state of a device. The same URL will generally be used for both getting and updating a device’ state.

Some example URLs are shown below:

  • GET http://one-hub.local/api/device/corner%20light/on would return whether the 'Corner Light' is on.

  • GET http://one-hub.local/api/device/corner%20light/colour would return whether the current colour of the 'Corner Light'.

  • POST http://one-hub.local/api/shortcut/all%20lights/on turns on all your lights

  • POST http://one-hub.local/api/room/living%20room/on turns on all your lights in the living room

  • POST http://one-hub.local/api/device/music%player/play would start playing music on your Sonos player

  • POST http://one-hub.local/api/device/music%player/mute would mute your player

  • POST http://one-hub.local/api/device/corner%20light/colour/255/0/0 will set your corner light to red

You can also use the HTTP ‘Accept’ header to control whether you get back a plain text response or one encoded in JSON (JavaScript Object Notation) interchange format.

We’ll now look at some examples of accessing the API using some common tools:

  • Your web browser
  • The command-line wget utility
  • The command-line curl utility

First of all, choose a device that has an on/off switch, such as a light bulb or power socket. We’ll use a Belkin WeMo Switch, called ‘WeMo Switch’, in this example, but you’ll need to use the name of your own device instead.

11.2.1. Making API requests with a web browser

You should be able to point your web browser at a URL such as: http://one-hub.local/api/device/WeMo%20Switch/on

You’ll get a login popup on your first attempt, and you should enter the username & password of the API user you created earlier. When the page loads you’ll see a ‘1’ or a ‘0’ which will tell you whether your ‘WeMo Switch’ device is on or off.

You won’t be able to do very much more with a standard web browser, but by using browser plugin you should be able to send POST requests and alter the ‘Accept’ header.

For example, using the HttpRequester plugin for Firefox:

  1. Open HttpRequester from the Tools menu (Ctrl+Alt+P)
  2. Enter http://one-hub.local/api/device/WeMo%20Switch/on as the Request URL
  3. Click the GET button to retrieve the current status of the switch
  4. Click POST to turn the switch on, if it isn’t already
  5. Change the end of the URL to be ‘off’, and send another POST request to turn the switch off again
  6. Click on the Headers tab and find the Accept header. Enter ‘application/json’ as the value, and click Add
  7. You will now get additional information in the Response shown in the right, such as {"success":1,"message":"OK","result":1}. This response will be more suitable for some applications and toolkits

Other plugins for Firefox and other browsers such as Chrome and Internet Explorer will work similarly.

11.2.2. Making API requests using wget

Here are some examples that use wget. You will need to add --user and --password to each example to specify the username & password of your API user.

# Get whether light is already on, saving 0 or 1 to output.txt
wget -q -O output.txt http://one-hub.local/api/device/47/on

# Get whether light is already on, returning a JSON structure
wget -q -O output.txt http://one-hub.local/api/device/47/on --header "Accept: application/json"

# Turn light on
wget -q -O output.txt http://one-hub.local/api/device/47/on --post-data=''

# Turn hall lights light off
wget -q -O output.txt http://one-hub.local/api/room/hall/off --post-data=''

# Toggle light status
wget -q -O output.txt http://one-hub.local/api/device/47/toggle --post-data=''

# Blink light 3 times
wget -q -O output.txt http://one-hub.local/api/device/47/blink/3 --post-data=''

11.2.3. Making API requests using curl

Similarly using curl, omitting ‘--user name:password’ for brevity.

# Get whether light is already on, displaying 0 or 1
curl http://one-hub.local/api/device/47/on

# Get whether light is already on, saving 0 or 1 to output.txt
curl -o output.txt http://one-hub.local/api/device/47/on

# Get whether light is already on, returning a JSON structure
curl -o output.txt http://one-hub.local/api/device/47/on -H "Accept: application/json"

# Turn light on
curl -X POST http://one-hub.local/api/device/47/on

# Toggle light status
curl  -X POST http://one-hub.local/api/device/47/toggle

# Blink light 3 times
curl -X POST http://one-hub.local/api/device/47/blink/3

# Shell script which uses curl
if [ `curl -s http://one-hub.local/api/device/my%light/on --user USER:PASS ` == 1 ]
then
  echo 'My Light is On'
else
  echo 'My Light is Off'
fi