Getting started 

This section describes the first steps needed in order to use the API. If you are new to REST APIs please read the About REST section first.


REST-API client

The only tool needed in this section is a browser with a REST-API client add-on to access the API. This document doesn’t cover the API access through a programming language since everybody may have its favorite language.

There are various free clients available; please pick one for your favourite browser in the browser add-on section.

In the following steps Postman for Chrome from the Google Webstore will be used. For Firefox the REST Client is another popular client.


Find your gateway

As first step the gateway IP address and port must be found.

This could be achieved by doing a GET request to https://phoscon.de/discover.

discover the gateway

The response body shows that the gateway has the IP address 192.168.192.32 and the API is reachable through port 8080.

Hint

If the above request doesn’t work, there are several other ways to find the gateway IP address as described in Discovery.


Acquire an API key

Any client that wants to access the API must provide a valid API key otherwise the access will fail.

To acquire an API key send a POST request to /api as follows. Use the IP address and the port of your gateway that you got during discovery.

Important

The request must contain a JSON object with the required field devicetype.

In some Rest clients it is mandatory to put ‘http://’ in front of the IP address of the gateway.

aquire api key failed

… something went wrong!

The returned HTTP status is 403 Forbidden. The response body provides further information about the raised error in the JSON object.

Unlock the gateway

The reason why the request failed is that the gateway was not unlocked. This mechanism is needed to prevent anybody from access to the gateway without being permitted to do so.

As described in the section Authorization unlock the gateway as follows:

  • In a new browser tab open the Phoscon App
  • Click on Menu → Settings → Gateway
  • Click on “Advanced” button
  • Click on the “Authenticate app” button

See: Phoscon App — Advanced Gateway Settings

Now the gateway is unlocked for 60 seconds.

Second attempt

Within 60 seconds after unlocking the gateway, go back to the REST client and repeat the acquire API key request as before. (just click on Send again)

aquire api key success

This time the request succeded with HTTP status 200 OK.

In the response body the new API key is in the field username. From now on this API key will be used in further API requests.


Get a list of all lights

With the API key from the last section it is now possible to access the full API.

To get a list of all available lights run a GET request to /api/<apikey>/lights as follows.

get all lights

In the response 3 lights where returned. There are serval things to note here.

  • The response contains not a list like [ ] of lights but a object { } with key/value pairs
  • Each light can be accessed by its id "17"
  • The light id is a key in the response object and the related value is a further object

Note

Ids are strings and even if they contain numbers never expect them to be “1”, “2”, “3”, … if the user removes light “2” the list will become “1”, “3”.


Get the details of a light

To get the detail of a light do a GET request to /api/<apikey>/lights/<id> as follows.

get light details

Turn light on/off

To turn a light on/off do a PUT request to /api/<apikey>/lights/<id>/state as follows.

turn light on/off

In the request body set the on value to true or false to turn the light on and off.


Dim the light with transition time

Dimming is done the same way as sending on/off by using the bri parameter; additionally specify a transition time in 1/10 seconds.

The following example dims the light in 5 seconds down.

dimm light


What’s next

To do some more advanced things with this API please refer to the API Endpoints documentation on the left side menu.