The Thingsquare REST API

The Thingsquare REST API makes it possible to interact with the system from anywhere.

API endpoints

API endpoints is the base URL used for all API calls. All API endpoints follow the same pattern:

https://<frontend-uuid>.<server>

Where frontend-uuid is a uuid (universally unique identifier) that is generated by the Thingsquare server and server is the name of the Thingsquare server. An example of an API endpoint is:

https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/

Each frontend is an API endpoint.

Sessions

All API requests are done within the context of a session. A session is defined by a cookie that must be passed along with each API request.

Creating a logged in session

A session is created by logging in with a user name and password. Those will typically be requested from the user.

To log in, POST the login and password to the /0/session/login endpoint. This call will create a new user session cookie and return the status of the operation.

Example:

 curl -c sessioncookie.txt -X POST --data login=dummy@example.com --data password=secret https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/session/login

We use the curl command to do an HTTPS POST to the API endpoint. The -c sessioncookie.txt option tells curl to print out the cookies to the file sessioncookie.txt so we can use the session cookie for later calls. The --data login=dummy@example.com is the login name and --data password=secret is the password.

If everything is ok, the call will result in the following output:

login-ok

The login-ok tells us that this user could be logged in.

The /0/session/login request may result in the following responses:
* login-ok: the user was successfully logged in.
* login-fail: the user could not be logged in.

Logging out of a user session

Before proceeding, we should quickly go through how to log out of a user session.

Logging out is as simple as POSTing to /0/session/logout:

curl -X POST -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/session/logout

Any further API access with this session cookie should now fail.

Other user operations: anonymous user creation, signup

There are a few other user operations possible through the API: anonymous session creation, and user signups. Anonymous user creation is done with a POST to /0/session/.

User signup is done by POSTing to /0/session/signup with the login and password parameters. Depending on the product configuration, this will cause a confirmation email to be sent to the user.

User data

The first operations we'll go through are the operations that we can do on user data and the session itself: getting and setting user data, logging out, and how to create user accounts.

Obtaining user data

Once a session has been established, we can use it to request data from the server. The first is requesting information about the user:

curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/user/

This will result in something like this:

{"login":"dummy@example.com","confirmed":true,"data":{}}

This is the JSON repressentation of the user state. The login is the user login name, the confirmed field tells us if this user has confirmed the login email address or not, and the data field holds data that is defined by us and set through the API.

Setting user data

The data part of the user information can be set through the API by POSTing to the /0/user/ endpoint.

Example:

curl -X POST --data somekey=somevalue -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/user/

If everthing goes allright, we'll get this response:

user-data-ok

We have now set a piece of user data, somekey, to the value somevalue. We should now be able to read this data back:

curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/user/

Should result in:

{"login":"dummy@example.com","confirmed":true,"data":{"somekey":"somevalue"}}

Device operations

Users can interact with devices that are nearby and remote. Nearby devices are typically discovered via Bluetooth beacons or local area network (WiFi) transmissions. Remote devices are registered with the user account and can be obtained from anywhere.

The product configuration determines if a user has access to information about nearby devices and if the devices can be registered to the user.

Requesting device information

If a user hears a nearby device, by hearing an auth broadcast from the device, the user may request information about the device via the API.

To request information about a nearby device, we do a GET operation to the /0/devices/<id> endpoint, where <id> is the device uuid or the auth key in hexadecimal format.

Example with an auth key:

curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/69af53d0659d3cd2e3af1858e10fcb92

If the user has the right to obtain information about this device, this request may elicit a response like this:

{"d":{"mode":"master","leds":"#000","group":"ff05::1"},"s":{"eui":"fc00::1:1","type":"LED bulb","p":"fc00::1"}}

Registering a device

To register a device for remote access, POST to /0/devices/ with the auth data as the parameter.

curl -X POST --data auth=69af53d0659d3cd2e3af1858e10fcb92 -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/

If the registration was successful, the response will be the uuid of the device:

{"id":"74977b98-7de6-4882-8f1e-4884e989f757"}

This uuid is used when getting or setting device data.

Device data

Device data comes in two forms: device variables, which are stored both on the device and on the server, and server variables, which are stored

Setting device data

Setting device data is done by POSTing to the /0/devices/<id>/<type>/<key> endpoint, where id is the device uuid, type is either d or s, and key is the key.

curl -X POST --data 'value=#ff007f' -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/74977b98-7de6-4882-8f1e-4884e989f757/d/leds

The variable will be created if it does not exist.

Getting device data

Getting device data is done by GETing the /0/devices/<id> endpoint:

curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/74977b98-7de6-4882-8f1e-4884e989f757/

This will return the full list of device and server variables, like this:

{"d":{"name":"Virtual light 4"},"s":{"eui":"fc00::1:4","platform":"Virtual device"}}

To get a specific variable, add the variable name to the URL. Server variables are available under the /0/devices/<id>/s endpoint and device variables under the /0/devices/<id>/d endpoint. For example, the device variable leds is /0/devices/<id>/d/leds.

For example,

curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/74977b98-7de6-4882-8f1e-4884e989f757/d/name

will return

"Virtual light 4"

Further reading

Now that we've gone through the main operations of the API, go ahead and read the
full REST API reference.