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.