Introduction

REST stands for Representational State Transfer and sets the ground for various modern web based APIs. The main idea behind REST is that everything is a resource and has a state.

Resources are represented by URLs like:

  • /lights - a collection of lights
  • /lights/1 - a single light
  • /lights/1/state - the current state of a light

API endpoints

All resources are provided by so called endpoints. The API endpoint documentation can be found in the menu on the left side.

Currently the following endpoints are available.

EndpointDescription
/config Interface to query and modify the gateway configuration.
/lights Interface for single lights.
/groups Interface for groups of lights.
/scenes Interface to the scenes of a group.
/schedules Interface for timed commands.
/touchlink Interface for touchlink commands.

More endpoints and functionality will be added in future.


Methods

Resources can be queried and modified with standard HTTP methods. Where GET, PUT, POST and DELETE are only a subset of all possible methods, they are by far the most used ones.

MethodDescription
GETQuery the content of a ressource.
PUTModifies a existing ressource.
POSTCreates a new ressource which did not exist before.
DELETEDeletes a ressource.

JSON

The contents of ressources are often expressed in Javascript Object Notation better known as JSON. That’s not a requirement of REST itself, in fact some APIs also use XML but JSON is by far more popular due to its simplicity.

The JSON format is a very simple but powerful notation to express structured objects and lists. The following example covers everything that can be expressed with JSON.

Example object

{
	"a_string": "this is a string",
	"a_number": 5,
	"a_list": [ 1, 2.0, 3, 4 ],
	"a_mixed_list": [ 2, {}, "name", 6, [ 1, 2 ,3 ] ],
	"a_nested_object": {
		 "foo": "bar"
		}
}
  • Strings are always double quoted "like this"
  • Keys and values are separated by a colon : and keys are always strings like "key"
  • Objects { } and lists [ ] might be empty and can be nested
  • Numbers can be integers 1 or fractional 0.5

That’s all about JSON.


URLs and the API key

When reading the API endpoint documentation URLs will look like /api/<apikey>/lights.

The /api prefix separates the API interface from the HTML5 web application which is reachable through the document root /.

Nearly every API request requires a so called API key which is a mandatory part of request URLs.

The API key has the only purpose to restrict access to the gateway. Remember the gateway is reachable through the whole local network and without the API key requirement anybody could control the lights.

Nevertheless all clients need to acquire API key by means of the configuration endpoint.


Benefits

  • Clients might access the API local or remote via network
  • Access from any desktop and mobile platform
  • Access from any programming language
  • All popular programming languages provide helper classes and functions to work with RESTful APIs
  • The format of requests and responses is human readable
  • Learning and using REST APIs is pretty straight forward

What’s next

Now you know the basics about REST. It’s time to move on to the Getting Started section which explains step by step how to acquire an API key and do some basic control of the lights.