The Thingsquare REST API Reference
Session methods
Every API invocation is done on a specific session. The session is identified by a session cookie created by the server and sent by the client along every subsequent request. The session methods creates and destroys a session.
Note: some curl
examples use the -b
parameter and some the -c
parameter. The difference between them is that the -b
parameter tells curl
to read cookies from a file whereas the -c
parameter tells curl
to write cookies to a file. The methods where the server supplies a new session cookie use the c
parameter for their examples and the methods where the server expects a session cookie use the -b
parameter.
POST /0/session/
: create anonymous session
Description
Create a new anonymous user session. A new session cookie will be returned for the new session. This session cookie is to be used for further requests during the session.
Parameters
None
Return values
200 user-ok
: a session already existed201 user-ok
: a new session was created
Example usage
$ curl -c sessioncookie.txt -X POST https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/session/
user-ok
POST /0/session/login
: create login session
Description
Create a user session with for a user. A new session cookie will be returned for the new session. This session cookie is to be used for further requests during the session.
Parameters
login
: the login namepassword
: the password, in cleartext
Return values
201 login-ok
: authentication succeeded and the user was successfully logged in403 login-fail
: authentication failed
Example usage
$ 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
login-fail
POST /0/session/logout
: logout from session
Description
Logs out of the current session. The session cookie will no longer be possible to use for future requests.
Parameters
None.
Return values
201 logout-ok
: the session was successfully logged out400 logout-fail
: there was no session registered with the session cookie
Example usage
$ curl -b sessioncookie.txt -X POST https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/session/logout
logout-ok
POST /0/session/signup
: sign up new user
Description
Creates a new user and sends out a confirmation email. If no session was registered, a new session is created.
Parameters
login
: the login namepassword
: the password, in cleartext
Return values
201 signup-ok
: the user was successfully signed up400 signup-fail-no-email
: user user name was not a valid email address400 signup-fail-already-exists
: user user name already exists
Example usage
$ curl -b sessioncookie.txt -X POST --data login=badloginname --data password=secret https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/session/signup
signup-fail-no-email
POST /0/session/resend
: resend confirmation email
Description
Send a new confirmation email to the user.
Parameters
login
: the login name
Return values
200 resend-ok
: a new confirmation email was successfully sent400 resend-fail
: a new confirmation email could not be sent
Example usage
$ curl -b sessioncookie.txt -X POST --data login=badloginname https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/session/resend
resend-fail
POST /0/session/recovery
: send password recovery email
Description
Send an email with a password recovery link to the user.
Parameters
login
: the login name
Return values
200 recover-ok
: a password recovery email was successfully sent400 recover-fail
: a password recovery email could not be sent
Example usage
$ curl -b sessioncookie.txt -X POST --data login=badloginname https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/session/recover
recover-fail
User data methods
The user data methods are used for storing and retrieving JSON data associated with the user.
GET /0/user/
: get user data
Description
Retrieve the user's JSON data object. The user's data object contains four fields:
login
(string): the login name of the userconfirmed
(boolean): a boolean value indicating if the user is confirmedauthcode
(string): a unique code that is used to identify the user with devices in the network. May change over timedata
(object): an opaque JSON data structure that can hold arbitrary data
Parameters
None
Return values
200
+ user data: the user data in JSON format404 not found
: no user session was found
Example usage
$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/user/
{"login":"","confirmed":false,"authcode":"cbcca1229ef0b9d588a1b148090fa67d","data":{}}
POST /0/user/
: store user data
Description
Store data in the user's data
field.
The data supplied in the data
parameter will be merged with the user's data. This makes it possible to store only a subset of the data.
Parameters
- field name: a string with the user's data.
Return values
200 user-data-ok
: the data was successfully stored413 user-data-failed
: the data was too large
Example usage
$ curl -b sessioncookie.txt -X POST --data test=data https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/user/
user-data-ok
$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/user/
{"login":"","confirmed":false,"authcode":"cbcca1229ef0b9d588a1b148090fa67d","data":{"test":"data"}}
$ curl -b sessioncookie.txt -X POST --data another=test https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/user/
user-data-ok
$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/user/
{"login":"","confirmed":false,"authcode":"cbcca1229ef0b9d588a1b148090fa67d","data":{"test":"data","another":"test"}}
Device methods
The device methods are used to retrieve device data, store device data, and register devices for remote access.
GET /0/devices/
: get all remote access devices
Description
Get information about all devices registered for remote access.
Parameters
None
Return values
200
+ device data: a JSON object of all device data, hashed by the device ID
Example usage
$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/
{"b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56":{"d":{"network-id":{"value":"8d6f953b730f4e4e","time":1468494129774,"acked":1468494129774,"syncacked":1468876125944,"synced":1468876109029},"mode":{"value":"deadleaf","time":1467199258562,"acked":1467199259016,"synced":1468876109029,"syncacked":1468876126171}},"s":{"platform":{"value":"thsq-sensortag","time":1468876126172}, <...>}}
GET /0/devices/<id>
: get one device
Description
Get information about one specific device that has been registered for remote access or is nearby.
Parameters
<id>
: the device ID for a remote access device, or the nearby ID for a nearby device
Return values
200
+ device data: a JSON object with the device data
Example usage
$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56
{"d":{"network-id":{"value":"8d6f953b730f4e4e","time":1468494129774,"acked":1468494129774,"syncacked":1468876125944,"synced":1468876109029},"mode":{"value":"deadleaf","time":1467199258562,"acked":1467199259016,"synced":1468876109029,"syncacked":1468876126171}},"s":{"platform":{"value":"thsq-sensortag","time":1468876126172}, <...>}
GET /0/devices/<id>/<type>/<name>
: get one variable
Description
Get one specific variable for a device
Parameters
<id>
: the device ID for a remote access device, or the nearby ID for a nearby device<type>
: the variable type, eitherd
,s
, ormeta
<name>
: the variable name
Return values
200
+ variable data: a JSON object with the variable data
Example usage
$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/s/platform
{"value":"thsq-sensortag","time":1468876126172}
GET /0/devices/<id>/<type>/<name>?latest=<latest>
: get variable history
Description
Get data history for a specific variable
Parameters
<id>
: the device ID for a remote access device, or the nearby ID for a nearby device<type>
: the variable type, eitherd
,s
, ormeta
<name>
: the variable name<latest>
: the number of data points to be retrieved
Return values
200
+ variable data: a JSON array with historical values for the variable
Example usage
$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/s/platform\?latest=2
[{"key":"platform","value":"thsq-sensortag","by":"device","type":"s","timestamp":1468876126172,"id":54968717},{"key":"platform","value":"thsq-sensortag","by":"device","type":"s","timestamp":1468852593002,"id":54800348}]
GET /0/devices/<id>/<type>/<name>?latest=<latest>
: get variable history
Description
Get data history for a specific variable
Parameters
<id>
: the device ID for a remote access device, or the nearby ID for a nearby device<type>
: the variable type, eitherd
,s
, ormeta
<name>
: the variable name<latest>
: the number of data points to be retrieved
Return values
200
+ variable data: a JSON array with historical values for the variable
Example usage
$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/s/platform\?latest=2
[{"key":"platform","value":"thsq-sensortag","by":"device","type":"s","timestamp":1468876126172,"id":54968717},{"key":"platform","value":"thsq-sensortag","by":"device","type":"s","timestamp":1468852593002,"id":54800348}]
POST /0/devices/
: register device for remote access
Description
Claim a device for remote access. The authentication token can be received either via a Bluetooth beacon (or other proximity communication) or from a network device.
Parameters
auth
: the device authentication token
Return values
201
+<device ID>
: the device was successfully registered for remote access,<device ID>
is the device's new access ID400 claim-fail
: could not register device for remote access
Example usage
$ curl -b sessioncookie.txt -X POST --data auth=123456789abcdef https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/
claim-fail
DELETE /0/devices/<id>
: remove a device from remote access
Description
Remove remote access for a device.
Parameters
None.
Return values
200 device-ok
: remote access for the device was successfully removed400 device-fail
: the device could not be found
Example usage
$ curl -b sessioncookie.txt -X DELETE --data value=120 https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56
device-ok
POST /0/devices/<id>/<type>/<name>
: set a device variable
Description
Set a device variable. The <type>
can be s
or d
. If <type>
is d
, variable data will be sent to the device.
The variable value can be set either as a string (with the value
parameter) or as a base64-encoded string (with the value64
parameter) to make it easier to set binary data values.
If <type>
is d
and no value is given, the device will be synchronized with the current value of the variable named <name>
.
If a d
variable is set and the device is currently available, the new value of the variable will be pushed to the device, but this method will return to the caller before the value has reached the device. The caller should use the GET /0/devices/<id>/d/<name>/
method to query for the successful acknowledgment of the variable to ensure that the variable has reached the device.
Parameters
value
: the variable valuevalue64
(optional): a base64-encoded value
Return values
200 device-ok
: the variable was successfully set400 device-fail
: the variable could not be set
Example usage
$ curl -b sessioncookie.txt -X POST --data value=120 https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/d/period
device-ok
DELETE /0/devices/<id>/<type>/<name>
: delete a device variable
Description
Delete a device variable.
If the variable is a d
variable, the deletion will be synchronized with the device.
Parameters
None.
Return values
200 device-ok
: the variable was successfully deleted400 device-fail
: the variable could not be deleted
Example usage
$ curl -b sessioncookie.txt -X DELETE --data value=120 https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/d/period
device-ok
POST /0/devices/<id>/
: send device command
Description
Send a the device command to a device.
Parameters
command
: the command to be sent, if the command is an ASCII stringcommand64
(optional): the base64 encoded version of the command string, if the command contains binary characterspriority
(optional): the priority of the command (0
: default urgency,1
: urgent,2
: most urgent)lifetime
(optional): the time, in milliseconds, that the command should be on the command queue before being removed
Return values
200 <command uuid>
: command transmission of command withcommand uuid
started
Example usage
$ curl -b sessioncookie.txt -X POST --data command=idfy https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/
043e6ba0-8cee-4519-b061-c3a263b7be18
Network methods
The network methods is used to query the network that the user currently is in. To announce the presence of a user, the user's client must broadcast the user's authcode
in repeated UDP messages on port 590. These messages are picked up by nearby access points and the backend can then match the devices that are in the same network as the user.
GET /0/network/
: get all available devices in the network
Description
The all device information for devices in the same network as the user.
Parameters
None
Return values
200
+ JSON string: a JSON object with all devices in the network, hashed by the devices' auth codes.
Example usage
$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/network/
{"fd92477f326aaa4de8b2d85122560591":{"d":{"period":{"value":"60","time":1464883503962,"acked":1464883503962,"syncacked":1468930674962,"synced":1468930674841},"mode":{"value":"master","time":1468930675543,"acked":1468930675543},"network-id":{"value":"8d6f953b730f4e4e","time":1468930675543,"acked":1468930675691},<...>}
Over-the-air firmware update methods
The firmware update methods are used to query the system for available firmware images and for starting and stopping a remote firmware update for a device.
GET /0/firmware/
: obtain available firmware images
Description
Retrieve the list of available firmware images.
Parameters
None
Return values
200
+ JSON string: a JSON array with all available firmware images
Example usage
$ curl -b sessioncookie.txt https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/firmware/
[{"name":"20160718/cc2538dk/client.signed","platform":"thsq-cc2538dk-bootloader","version":1468838806,"info":{"platforms":{"from":["thsq-cc2538dk"],"to":{"platform":"thsq-cc2538dk","name":"TI CC2538dk"}}}}, <...>]
POST /0/devices/<id>/fw/<name>
: start a firmware update
Description
Start a firmware update for the device with ID <id>
.
The device must be in the connected state for the firmware update to commence. To set the device to the connected state, the d
variable mode
must be set to connected
. Once the device has connected to the backend, the meta
variable state
will become connected
. It is the responsibility of the caller to ensure that these conditions are met before calling this method.
Parameters
None
Return values
200 device-ok
: device firmware update was started400 device-fwup-name-fail
: firmware name could not be found400 device-fwup-start-fail
: device firmware update could not be started
Example usage
$ curl -b sessioncookie.txt -X POST https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/fw/20160718/sensortag/client.signed
device-ok
DELETE /0/devices/<id>/fw
: cancel an ongoing a firmware update
Description
Cancel an ongoing firmware update for a device.
Parameters
None
Return values
- `200 firmware-ok': device firmware update was canceled
400 firmware-fail
: device firmware update could not be canceled
Example usage
$ curl -b sessioncookie.txt -X DELETE https://0ac48bf3-9fab-4bad-8455-e394808eda6b.developer.thingsquare.com/0/devices/b9b5a63b-85c1-4cc8-ab6e-8c43c2d54d56/fw
device-ok