Welcome to CloudThing’s documentation!¶
Contents:
General Concept¶
CloudThing Cloud Platform is a software layer between hardware devices and Internet of Things applications. It may be considered as middleware for end-to-end IoT solutions.
CloudThing features set of APIs for connecting and managing devices, as well as for services and apps development and management.
The CT cloud platform is multi-tenant application with strong separation between tenants’ data. Every new tenant has his own virtual host created accessible by {shortName}.cloudthing.io. Short names are automatically generated bundles of two words, if you want custom one get in touch hello@cloudthing.io.
Example: if generated name was vanilla-ice then tenant’s vhost would be exposed via vanilla-ice.cloudthing.io and services would be accessible via:
- Control Center: https://vanilla-ice.cloudthing.io,
- HTTP API: https://vanilla-ice.cloudthing.io/api/v1,
- MQTT API: mqtts://vanilla-ice.cloudthing.io:8883,
- MQTT Websockets API: wss://vanilla-ice.cloudthing.io:9001/mqtt,
- HTTP connector API: http://vanilla-ice.cloudthing.io:81/v1,
etc.
Getting Started¶
Quickstart with web application¶
During this 5 minute quickstart, you’ll create and model heat controller, register new device, automate it and set an alert with SMS notification.
Registration¶
Go to https://app.cloudthing.io
, choose I don’t have an account and follow the instructions. After a successful registration, you will receive a new virtual host with autogenerated tenant’s name. We will send you an email with confirmation link. Without the confirmation, you won’t be able to log into your account, so make sure that you entered correct email address.
Please remember your tenant’s name and the URL to your instance of the CloudThing platform!
Create new product¶
Once you’ve logged in into the web application, navigate to Things > Product and create a new one by clicking on plus mark. Choose name and (optionally) description (e.g. “Heat controller”, “This Heat Controller is a set of Smart Home ecosystem”). Click on Save & configure.
Go to DATA tab and add a new entry, set values in columns ‘Data ID’, ‘Name’ and ‘Description’ to “temp”, “Temperature” and “Temperature reported by controller” respectively. Then go to COMMANDS and add new entry with “turn”, “Turn” and “Turns heating on or off” in ‘Command ID’, ‘Name’ and ‘Description’ columns. That way you declare what information is sent by devices and what messages they receive. This step is not necessary - the platform will register new data at arrival, however setting these resources beforehand makes it easier to configure the system.
Register & connect device¶
If you completed the previous step, go to DEVICES and add a new one. A new ID/token pair will be generated, click on ID and go to Device card.
As you can see the device is not active which means that it has never sent any messages to the platform. To start sending measurements expand a menu on Connectivity card and choose How to connect?. Copy value from MQTT or HTTP card (you’ll have to have a MQTT client installed on your computer if want to use it, for HTTP you just need curl which is preinstalled on most Linux distributions).
Execute command from your computer’s console, for example:
curl -H "Content-Type: application/json" \
-u "dxM18Pd_T3yfsdds1x9AxFQ:HMb7Ug0nv3h8duyVfwwh5jIgce81dg3l" \
-X POST https://vanilla-ice.cloudthing.io:444/v1/dxM18Pd_T3yfsdds1x9AxFQ/data \
-d '{"r":[{"k":"temp","v":36.6}]}'
You should see a new message and a point on application’s chart. Try replacing default value with others and see how the chart is changing.
Create analytics flow¶
Now, when you have a working simulated device, you can create data flows and analytics. Navigate to Analytics > Stream & Batch and create new pipeline. Click on its name in order to edit the diagram.
You will see a blank canvas with nodes on the side to choose from. Drag a Data node and drop it on the canvas. This node represents data that arrive to the system. Click on it to edit options within the node. Choose the product which you defined earlier as a source entity. Add a Filter node and set its expression to {{data.temp}} > 40
. Connect Data node to the filter. Filter node will pass only those packets which fulfill given condition. The last step is to add a sink node - it will perform an action for every packet it receives. Choose an SMS node, fill the phone number (with ‘+’ sign and your country’s calling code) and write a message for you, e.g. The temperature is {{data.temp}}. It is too hot!
. Connect filter node to the SMS node.
When nodes are ready, click the SAVE button. If everything is fine with the diagram, you will see The diagram was successfully saved. It can be deployed now. message. Otherwise, warning signs will appear on the nodes and you will have to resolve these errors in order to proceed. When the diagram is ready to be deployed, you can “turn it on”: just click the switch next to SAVE button. You should see a message The diagram was successfully deployed.. That means that your flow is operational and is waiting for data to arrive.
You can test it by sending messages, just like you did it earlier. Try sending some messages with different temp values and see if you receive an SMS!
CloudThing APIs¶
Contents:
Connectors APIs¶
Connectors are connectivity layer of CloudThing software stack and consist of APIs for Open Source IoT protocols, networking stacks (Sigfox, LoRaWAN) and others. It is possible to develop custom connector if required (ask us about it: hello@cloudthing.io).
General¶
The connectors share a general concept of channels. CloudThing creates 4 messaging channels for every device in system:
- Data: v1/{deviceId}/data
- Events: v1/{deviceId}/events
- Commands: v1/{deviceId}/commands
- Responses: v1/{deviceId}/responses
Data channel is used for device-to-cloud communication and is intended to be used as ordinary, regular measurements stream (eg. temperature, pressure).
Events channel is used for device-to-cloud communication and is intended to be as non-regular event reporting stream (eg. button pressed). It is possible for device to get response from cloud using this channel, so one may consider it as a remote (on cloud) function execution.
Commands channel is used for cloud-to-device communication and is intended to be used for sending execution commands or configuration options from user/application to device (eg. turn on LED, set config).
Responses is bidirectional channel supporting commands and events. It differs between connectors.
Serialization formats¶
CloudThing connectors support different serialization formats including:
- JSON,
- CBOR,
- Google Protocol Buffers,
- custom formats.
Only messages sending via data channel requires to use one of supported serialization formats.
JSON
The basic stucture of data message is:
{
"records": [
{"key":"temp", "value": 36.6},
{"key":"bat", "value": 3.5}
]
}
Value can by any JSON base type object (number, string, bool). Soon, we’ll enable usage of nested JSON object.
Every entry may also include time as RFC3339-formatted string, Unix timestamp (number) of diff between previous point (number):
{
"records": [
{"key":"temp", "value": 36.6, "time":"2016-05-03T13:24:16Z"},
{"key":"bat", "value": 3.5, "time": 6}
]
}
It is also possible to geo-locate measurements by adding:
{
"records": [
{
"key":"temp",
"value": 36.6,
"geo": {
"lat": 52.24325,
"lon": 26.32256
}
},
{"key":"bat", "value": 3.5}
]
}
JSON serialization supports also indexing of entries what is really helpful in decreasing message size when sending lot of entries in one message:
{
"index": ["temp", "bat"],
"records": [
{"key":0, "value": 36.6},
{"key":1, "value": 3.5}
]
}
To reduce size even more, one can use shorter field names:
{
"i": ["temp", "bat"],
"r": [
{
"k":0,
"v": 36.6,
"g": {
"lt": 52.24325,
"ln": 26.32256
}
},
{"k":1, "v": 3.5}
]
}
CBOR
CBOR or Constrained Binary Object Representation is JSON-compatible binary format designed for constrained devices.
This serialization format is higly recommended for production and most use-cases.
When using it, one can pack data as shown for JSON with short field names.
Google Protocol Buffers
Since Protobuf is unstructured format and requires struct definitions when (de)serializing, you’ll need to provide us with your .proto file. Get in touch hello@cloudthing.io.
Custom
You can use custom format and transform it to our internal one by implementing transform function which we use on every incoming data point.
MQTT API¶
MQTT is a lightweight messaging protocol implementing publish/subscribe model.
MQTT connector allows devices to use it for cloud communication.
Broker
MQTT connector broker allows TCP and TLS connections on ports 1883 and 1884 respectively of virtual host (eg. tenant-name.cloudthing.io:1883).
Authentication
Device has to provide proper authentication credentials as MQTT’s username and password. Client ID is not taking into account during authentication process.
- Username: {tenant-name}:{deviceId},
- Password: {deviceToken}.
Topics
For publishing measurements to data channel one has to use topic v1/{deviceId}/data?ct=json where ct parameter defines content type and may be on of:
- json,
- cbor,
- proto,
- custom.
custom is default one.
The publish example using mosquitto_pub:
mosquitto_pub -h short-name.cloudthing.io \
-u short-name:SoMEc0MpL1Cat3D1D \
-P 3xAmpLeT0K3n \
-t v1/SoMEc0MpL1Cat3D1D/data?ct=json \
-m '{"r":[{"k":"temp","v":36.6}]}'
New event may be generated by publish to topic v1/{deviceId}/events/{eventId}.
To recieve commands, device needs to subscribe on topic v1/{deviceId}/commands/+. Every incoming message will have command id (name) as a last part of MQTT topic.
HTTP API¶
HTTP is a well-known and widely implemented protocol, although it is considered as too heavy for small, constrained devices.
Host
HTTP connector allows devices to use unencrypted or encrypted (TLS) version of protocol.
The HTTP server listens on port 81 and HTTPS on port 444 of tenant’s virtual host.
Authentication
The connector supports Basic authentication with:
- Username: {deviceId},
- Password: {deviceToken}
Content Type
Connector supports all available serialization formats and maps “Content-Type” header to format as follows:
- “application/json” -> JSON,
- “application/cbor” -> CBOR,
- “application/octet-stream” -> PROTOBUF,
- other -> CUSTOM.
Endpoints
Endpoints are created by appending channel name to base path:
- Data (POST): {scheme}://{short-name}.cloudthing.io:{port}/v1/{deviceId}/data
- Events (POST): {scheme}://{short-name}.cloudthing.io:{port}/v1/{deviceId}/events/{eventId}
- Commands (GET): {scheme}://{short-name}.cloudthing.io:{port}/v1/{deviceId}/commands
- Firmware (GET): {scheme}://{short-name}.cloudthing.io:{port}/v1/deviceId}/fw/dl/{firmwareId}
Commands supports streaming (subscribtion) and long connections (similar to MQTT’s subscribe). Streaming must be enabled by adding ?stream={keepAliveMilliseconds} as query parameter, where keepAliveMilliseconds is a period of time after which cloud will send blank message to keep connection alive. Chunked streaming is implemented with respect to Chunked responses specification, command id (key) is send as parameter of every chunk.
Example sending data:
curl -H "Content-Type: application/json" \
-u "SoMEc0MpL1Cat3D1D:3xAmpLeT0K3n" \
-X POST https://short-name.cloudthing.io:444/v1/SoMEc0MpL1Cat3D1D/data \
-d '{"r":[{"k":"temp","v":36.6}]}'
Example subscribtion for commands:
curl -H "Content-Type: application/json" \
-u "SoMEc0MpL1Cat3D1D:3xAmpLeT0K3n" \
-X GET https://short-name.cloudthing.io:444/v1/SoMEc0MpL1Cat3D1D/commands?stream=10000
CoAP API¶
CoAP connector and API will be released soon. Note, that it will be recommended way of connecting constrained devices.
Sigfox¶
CloudThing is integrated with Sigfox backend and it is possible to gather all data from Sigfox deployment in our cloud. To start using it, you need to enable Sigfox connector and choose parsing JavaScript function in Control Center application. Then, you need to configure your Sigfox backend with HTTP POST callback as follows:
http://short-name.cloudthing.io:82/sigfox/{{productId}}?id={device}&data={data}
Example:
http://vanilla-ice.cloudthing.io:82/sigfox/SoMEc0MpL1Cat3D1D?id={device}&data={data}
The Things Network¶
CloudThing is integrated with TTN network and it is possible to create devices and connect them via OTAA to cloud. The connector will be enabled in Week 22.
LoRaWAN networks¶
It is possible to connect to commercial LoRaWAN network or deploy private one with our software stack. Ask us about it hello@cloudthing.io.
Application APIs¶
The family of Application APIs have been designed for integrating 3rd party services, creating custom applications and managing your data and devices.
Contents:
HTTP REST API Reference¶
REST API Core Concepts¶
The following information is essential to understanding how the CloudThing API works.
Base URL¶
This API is accesible via /api/v1
.
The full path for example tenant vanilla-ice
would be:
https://vanilla-ice.cloudthing.io/api/v1
Methods¶
API uses following HTTP verbs (methods):
Method | Target | Action |
---|---|---|
GET |
collection | Retrieves collection. |
GET |
item | Retrieves single item. |
POST |
collection | Creates new item in collection. |
POST |
item | Updates item. |
DELETE |
item | Deletes item. |
Note
API does not support PUT since it is not possible to replace objects and PATCH which as we believe is commonly misunderstood and being used in wrong way (for updates).
Serialization format¶
Currently REST API uses only JSON as serialization format and requires proper Content-Type
(POST
) and Accept
(POST
, GET
) headers in every client request.
TLS¶
HTTP API accepts only encrypted (TLS) requests. All HTTP non-TLS requests will be redirected. The HTTP server listens on standard port 443 of tenant’s virtual host.
Warning
Note that due to redirection of HTTP request port 80 is open, so your credentials will still be exposed if you send request without TLS encryption.
Authentication & authorization¶
CloudThing REST API supports Basic and Bearer (JWT) authentication. Since API can be used with not only API keys but also users’ (official and end) credentials, one should provide following authorization data.
Requester | Username | Password | Header & query |
---|---|---|---|
API key | key |
secret |
Header: Authorization: Basic base64({key}:{secret}) |
Official user | email |
password |
Header: Authorization: Basic base64({email}:{password}) |
User | email |
password |
Header: Authorization: Basic base64({email}:{password}) , Query: application=applicationId |
To obtain JWT token one should send POST request to /api/v1/auth/token
endpoint with Basic auth.
Requester | Token | Header & query |
---|---|---|
API key/Official user/User | access_token |
Header: Authorization: Bearer {access_token} |
Collections¶
When requesting collection you can add additional query parameters:
Attribute | Type | Default Value | Description |
---|---|---|---|
limit |
Integer | 25 | Requested maximum number of returned items in single response. |
page |
Integer | 1 | Requested page of returned items. |
API will return meta data in top level of object and items in items
array.
Metadata is:
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
size |
Integer | N/A | Number of all items in collection. |
limit |
Integer | N/A | Requested maximum number of returned items in single response. |
page |
Integer | N/A | Requested page of returned items in cuurent response. |
prev |
Link | N/A | The URL to previus page of collection. |
next |
Link | N/A | The URL to next page of collection. |
Retrieving collection:
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0ft3nAnT/applications?limit=2&page=1" \
-H 'Accept: application/json'
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0ft3nAnT/applications?limit=2&page=1",
"size": 3,
"limit": 2,
"page": 1,
"items": [
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/applications/aPp1iCaT10n01"
// JSON continues here, trunked for readability
},
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/applications/ArFd87gf10n02"
// JSON continues here, trunked for readability
}
],
"next": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0ft3nAnT/applications?limit=2&page=2"
}
}
Linking & expanding¶
CloudThing API implements great linking concept developed by awesome people at stormpath.com
.
Every response (collection or item) is identified by its URL in href
field, there is no other id provided. All relations between objects use this method and embed href
in JSON object named as relative. It is possible to expand relations in single request (one level only) by providing relation name to expand
parameter in query. You can expand several relations by putting them comma-seprated and even paginate and limit results if relation is collection by adding (limit:{limit},offset:{offset})
after relation name.
In short words:
Just hit /api/v1/tenants/current
and start exploring!
Link in resource body:
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA" \
-H 'Accept: application/json'
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA",
// JSON continues here, trunked for readability
"tenant": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0ft3nAnT"
}
}
Expanded link in resource body:
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA?expand=tenant" \
-H 'Accept: application/json'
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA",
// JSON continues here, trunked for readability
"tenant": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0ft3nAnT"
"shortName": "vanilla-ice",
// JSON continues here, trunked for readability
}
}
Expanded link to collection:
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA?expand=clusters(limit:2,page:1)" \
-H 'Accept: application/json'
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA",
// JSON continues here, trunked for readability
"clusters": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA/clusters",
"size": 3,
"limit": 2,
"page": 1,
"items": [
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/clusters/cLusCaT10n01"
// JSON continues here, trunked for readability
},
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/clusters/Ar76fya10n02"
// JSON continues here, trunked for readability
}
],
"next": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA/clusters?limit=2&page=2"
}
}
}
Tenant¶
Description
Tenant is an organization on behalf of which user or API key requests data. When registering an account at CloudThing.io the organization and user within it are created.
Tenant URL
/tenants/{tenantId}
Tenant Attributes
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
name |
String | 1 < N < 256 characters | Full name of Tenant, eg. organization/company name. |
shortName |
String | 1 < N <= 63 characters | Human-readable unique key. This key is unique and assigned by CloudThing upo registration. If you would like to change it, please contact us. |
createdAt |
String | RFC3339 Datetime | Indicates when this resource was created. |
updatedAt |
String | RFC3339 Datetime | Indicates when this resource’s attributes were last modified. |
custom |
Object | N/A | A custom structure you can store your own custom fields in. |
limits |
Object | N/A | An embedded object containing information about available limits of tokens, SMSs and emails. |
directories |
Link | N/A | A link to a Collection of all the Directories mapped to this Tenant. |
applications |
Link | N/A | A link to a Collection of all the Applications mapped to this Tenant. |
products |
Link | N/A | A link to a Collection of all the Products mapped to this Tenant. |
devices |
Link | N/A | A link to a Collection of all the Devices mapped to this Tenant. |
analytics |
Link | N/A | A link to a Collection of all the Analytics configured for this Tenant. |
users |
Link | N/A | A link to a Collection of all the Users mapped to this Tenant. |
statistics |
Link | N/A | A link to a Collection of all the Statstics available for this Tenant. |
Tenant Example
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT",
"name": "user@example.com's organization",
"shortName": "vanilla-ice",
"createdAt": "2016-05-15T11:18:33Z",
"updatedAt": "2016-05-15T11:18:33Z",
"limits": {
"tokens": {
"total": 5,
"used": 1
},
"sms": {
"total": 5,
"used": 0
},
"emails": {
"total": 5,
"used": 0
}
},
"custom": {
}
"directories": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT/directories"
},
"applications": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT/applications"
},
"products": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT/products"
},
"devices": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT/devices"
},
"analytics": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT/analytics"
},
"users": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT/users"
},
"statistics": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT/statistics"
}
}
Tenant Operations¶
Operation | Optional Query Parameters | Description |
---|---|---|
GET /tenants/current |
N/A | Retrieves the Tenant associated with the current API key. The response will be a 302 Redirect . You will find the location of the Tenant in a Location header and response body, although most REST libraries and web browsers will automatically issue a request for it. |
GET /tenants/{tenantId} |
N/A | Retrieves the Tenant with the specified ID. |
Retrieves link to current tenant:
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/tenants/current" \
-H 'Accept: application/json'
Response:
HTTP/1.1 302 Found
Content-Type: application/json
Location: https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT
{
"tenant": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT"
}
}
Retrieves tenant:
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT" \
-H 'Accept: application/json'
It is possible to retrieve other independent resources using the Tenant for look-up.
Operation | Optional Query Parameters | Description |
---|---|---|
GET /tenants/{tenantId}/{resourceName} |
Pagination, Sorting | Retrieves a collection of all of a Tenant’s associated resources of the specified type. Possible resource types are: directories , applications , products , devices , analytics , users , and statistics . |
Retrieving a Collection Associated with a Tenant
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT/products" \
-H 'Accept: application/json'
This query would retrieve a collection containing all the Products associated with the specified Tenant.
Directory¶
Description
Directory is a container for User and Usergroup resources. Every user is unique by email within Directory only. You can attach Directory to Application for storing end-users accounts. Your accounts for managing CloudThing are also stored in offcial Directory which cannot be deleted.
Directory URL
/directories/{directoryId}
Directory Attributes
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
name |
String | 1 < N < 256 characters | Name of Directory. |
createdAt |
String | RFC3339 Datetime | Indicates when this resource was created. |
updatedAt |
String | RFC3339 Datetime | Indicates when this resource’s attributes were last modified. |
official |
Boolean | N/A | Indicates whether it;s the official Directory or not. |
description |
String | N/A | The description of Directory which may describes it’s purpose. |
custom |
Object | N/A | A custom structure you can store your own custom fields in. |
tenant |
Link | N/A | A link to a Tenant owning this Product. |
users |
Link | N/A | A link to a Collection of all the Users stored in this Directory. |
usergroups |
Link | N/A | A link to a Collection of all the Usergroups stored in this Directory. |
applications |
Link | N/A | A link to a Collection of all the Applications mapped to this Directory. |
Directory Example
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/directories/Som31D0fD1r3cTo",
"name": "Smart application directory",
"createdAt": "2016-05-15T11:18:33Z",
"updatedAt": "2016-05-15T11:18:33Z",
"official": false,
"description": "This directory is used for end-users of our Smart Home application",
"custom": {
},
"tenant": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT"
},
"users": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/directories/Som31D0fD1r3cTo/users"
},
"usergroups": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/directories/Som31D0fD1r3cTo/usergroups"
},
"applications": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/directories/Som31D0fD1r3cTo/applications"
}
}
Directory Operations¶
Operation | Attributes | Description |
---|---|---|
POST /tenants/{tenantId}/directories |
Required: name . Optional: description , custom . |
Creates new directory. |
Operation | Optional Query Parameters | Description |
---|---|---|
GET /directories/{directoryId} |
expand |
Retrieves the Directory with the specified ID. Expandable links: users , usergroups , applications , tenant . |
Operation | Attributes | Description |
---|---|---|
POST /directories/{directoryId} |
name , description , custom |
Updates the Directory with the specified ID. |
Operation | Optional Query Parameters | Description |
---|---|---|
DELETE /directories/{directoryId} |
N/A | Deletes the Directory with the specified ID. |
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/directories/Som31D0fD1r3cTo" \
-H 'Accept: application/json'
It is possible to retrieve other independent resources using the Directory for look-up.
Operation | Optional Query Parameters | Description |
---|---|---|
GET /directories/{directoryId}/{resourceName} |
Pagination, Sorting | Retrieves a collection of all of a Directory’s associated resources of the specified type. Possible resource types are: users , usergroups and applications . |
Retrieving a Collection Associated with a Directory
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/directories/Som31D0fD1r3cTo/users" \
-H 'Accept: application/json'
This query would retrieve a collection containing all the Users associated with the specified Directory.
Usergroup¶
Description
Usergroup is a container for User resources. Every user can belong to many Groups.
Directory URL
/usergroups/{usergroupId}
Usergroup Attributes
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
name |
String | 1 < N < 256 characters | Name of Usergroup. |
createdAt |
String | RFC3339 Datetime | Indicates when this resource was created. |
updatedAt |
String | RFC3339 Datetime | Indicates when this resource’s attributes were last modified. |
custom |
Object | N/A | A custom structure you can store your own custom fields in. |
tenant |
Link | N/A | A link to the Tenant owning this Usergroup. |
directory |
Link | N/A | A link to the Directory this Usergroup is stored in. |
users |
Link | N/A | A link to a Collection of all the Users assigned to this Usergroup. |
memberships |
Link | N/A | A link to a Collection of all the Memberships of this Usergroup. |
Usergroup Example
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/usergroups/Som31D0fOoZ3rGru",
"name": "Home owners",
"createdAt": "2016-05-15T11:18:33Z",
"updatedAt": "2016-05-15T11:18:33Z",
"custom": {
},
"tenant": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT"
},
"directory": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/directories/Som31D0fD1r3cTo"
},
"users": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/usergroups/Som31D0fOoZ3rGru/users"
},
"memberships": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/usergroups/Som31D0fOoZ3rGru/memberships"
}
}
Usergroup Operations¶
Operation | Attributes | Description |
---|---|---|
POST /directories/{directoryId}/usergroups |
Required: name . Optional: custom . |
Creates new usergroup. |
Operation | Optional Query Parameters | Description |
---|---|---|
GET /usergroups/{usergroupId} |
expand |
Retrieves the Usergroup with the specified ID. Expandable links: users , memberships , directory , tenant . |
Operation | Attributes | Description |
---|---|---|
POST /usergroups/{usergroupId} |
name , custom |
Updates the Usergroup with the specified ID. |
Operation | Optional Query Parameters | Description |
---|---|---|
DELETE /usergroups/{usergroupId} |
N/A | Deletes the Usergroup with the specified ID. |
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/usergroups/Som31D0fOoZ3rGru" \
-H 'Accept: application/json'
It is possible to retrieve other independent resources using the Usergroup for look-up.
Operation | Optional Query Parameters | Description |
---|---|---|
GET /usergroups/{usergroupId}/{resourceName} |
Pagination, Sorting | Retrieves a collection of all of a Usergroup’s associated resources of the specified type. Possible resource types are: users and memberships . |
Retrieving a Collection Associated with a Usergroup
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/usergroups/Som31D0fOoZ3rGru/users" \
-H 'Accept: application/json'
This query would retrieve a collection containing all the Users associated with the specified Usergroup.
User¶
Description
User represents a real person’s account - either managing CloudThing’s Tenant ot using end solutions.
User URL
/users/{userId}
User Attributes
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
email |
String | 1 < N < 256 characters | User’s email address. |
firstName |
String | 1 < N < 256 characters | User’s first name. |
surname |
String | 1 < N < 256 characters | User’s surname. |
createdAt |
String | RFC3339 Datetime | Indicates when this resource was created. |
updatedAt |
String | RFC3339 Datetime | Indicates when this resource’s attributes were last modified. |
activated |
Boolean | N/A | Indicates wheter user activated the account (eg. by email verification). |
custom |
Object | N/A | A custom structure you can store your own custom fields in. |
tenant |
Link | N/A | A link to the Tenant owning this User. |
directory |
Link | N/A | A link to the Directory this User is stored in. |
applications |
Link | N/A | A link to a Collection of all the Applications this User has access to. |
usergroups |
Link | N/A | A link to a Collection of all the Usergroups this User belongs to. |
memberships |
Link | N/A | A link to a Collection of all the Memberships of this User. |
devices |
Link | N/A | A link to a Collection of all the Devices this User has rights to. |
User Example
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/users/Som31DUuZ3R0f",
"email": "john.doe@cloudthing.io",
"firstName": "John",
"surname": "Doe",
"createdAt": "2016-05-15T11:18:33Z",
"updatedAt": "2016-05-15T11:18:33Z",
"activated": true,
"custom": {
},
"tenant": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT"
},
"directory": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/directories/Som31D0fD1r3cTo"
},
"applications": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/users/Som31DUuZ3R0f/applications"
},
"usergroups": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/users/Som31DUuZ3R0f/usergroups"
},
"memberships": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/users/Som31DUuZ3R0f/memberships"
},
"devices": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/users/Som31DUuZ3R0f/devices"
}
}
User Operations¶
Operation | Attributes | Description |
---|---|---|
POST /directories/{directoryId}/users |
Required: email , password . Optional: firstName , surname , custom . |
Creates new user. |
Operation | Optional Query Parameters | Description |
---|---|---|
GET /users/current |
N/A | Retrieves the User associated with the current authorization data. The response will be a 302 Redirect . You will find the location of the User in a Location header and response body, although most REST libraries and web browsers will automatically issue a request for it. |
GET /users/{userId} |
expand |
Retrieves the Usergroup with the specified ID. Expandable links: applications , usergroups , memberships , devices , directory , tenant . |
Operation | Attributes | Description |
---|---|---|
POST /users/{userId} |
email , password , firstName , surname , custom |
Updates the User with the specified ID. |
Operation | Optional Query Parameters | Description |
---|---|---|
DELETE /users/{userId} |
N/A | Deletes the User with the specified ID. |
Retrieves link to current User:
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/users/current" \
-H 'Accept: application/json'
Response:
HTTP/1.1 302 Found
Content-Type: application/json
Location: https://vanilla-ice.cloudthing.io/api/v1/users/Som31DUuZ3R0f
{
"user": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/users/Som31DUuZ3R0f"
}
}
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/users/Som31DUuZ3R0f" \
-H 'Accept: application/json'
It is possible to retrieve other independent resources using the User for look-up.
Operation | Optional Query Parameters | Description |
---|---|---|
GET /users/{userId}/{resourceName} |
Pagination, Sorting | Retrieves a collection of all of a User’s associated resources of the specified type. Possible resource types are: applications , devices , usergroups and memberships . |
Retrieving a Collection Associated with a User
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/users/Som31DUuZ3R0f/applications" \
-H 'Accept: application/json'
This query would retrieve a collection containing all the Applications associated with the specified User.
Membership¶
Description
Membership represents assignment of User to Usergroup.
Membership URL
/memberships/{membershipId}
Membership Attributes
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
createdAt |
String | RFC3339 Datetime | Indicates when this resource was created. |
updatedAt |
String | RFC3339 Datetime | Indicates when this resource’s attributes were last modified. |
user |
Link | N/A | A link to the User this Membership is about. |
usergroup |
Link | N/A | A link to the Usergroup this Membership is about. |
Membership Example
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/memberships/Som31D0fMeM83rSh1P",
"createdAt": "2016-05-15T11:18:33Z",
"updatedAt": "2016-05-15T11:18:33Z",
"user": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/users/Som31DUuZ3R0f"
},
"usergroup": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/usergroups/Som31D0fOoZ3rGru"
}
}
Membership Operations¶
Operation | Attributes | Description |
---|---|---|
POST /usergroups/{usergroupId}/memberships |
Required: user . |
Assigns given user to usergroup. |
POST /users/{userId}/memberships |
Required: usergroup . |
Assigns user to given usergroup. |
Operation | Optional Query Parameters | Description |
---|---|---|
GET /memberships/{membershipId} |
expand |
Retrieves the Membership with the specified ID. Expandable links: user , usergroup . |
Operation | Optional Query Parameters | Description |
---|---|---|
DELETE /memberships/{membershipId} |
N/A | Deletes the Membership with the specified ID. |
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/memberships/Som31D0fMeM83rSh1P" \
-H 'Accept: application/json'
API Key¶
Description
API keys are used for authorization during CloudThing API operations.
API Key URL
/apikeys/{apikeyId}
API Key Attributes
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
name |
String | 1 < N < 256 characters | Name of API key. |
key |
String | 25 characters | API key. |
secret |
String | 32 characters | API secret. May be obtained only once in response for API key create request. |
createdAt |
String | RFC3339 Datetime | Indicates when this resource was created. |
updatedAt |
String | RFC3339 Datetime | Indicates when this resource’s attributes were last modified. |
status |
String (enum) | ENABLED , DISABLED |
Presents status of API key. |
description |
String | N/A | The description of API key which may describes it’s purpose. |
custom |
Object | N/A | A custom structure you can store your own custom fields in. |
tenant |
Link | N/A | A link to a Tenant owning this API key. |
API key Example
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/apikeys/AP1k3y1D3XamP13",
"name": "CRM key",
"key": "cJyGHVM1yIKoGQZowZXQz934e",
"secret": "sIe7QxDach1l4xNzmrKNTH5TVn9eV9PJ",
"createdAt": "2016-05-15T11:18:33Z",
"updatedAt": "2016-05-15T11:18:33Z",
"status": "ENABLED",
"description": "This API key is used in our custom CRM integration",
"custom": {
},
"tenant": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT"
}
}
Warning
The API key secret will be returned only once as a part of response for API key create request. You will not be able to retrieve that secret again. You can also create API key and download secret through CloudThing Control Center web application or CloudThing CLI.
API key Operations¶
Operation | Attributes | Description |
---|---|---|
POST /tenants/{tenantId}/apikeys |
Optional: name , description , custom , status . |
Creates new API key. |
Operation | Optional Query Parameters | Description |
---|---|---|
GET /apikeys/{apikeyId} |
expand |
Retrieves the API key with the specified ID. Expandable links: tenant . |
Operation | Attributes | Description |
---|---|---|
POST /apikeys/{apikeyId} |
name , description , custom , status |
Updates the API key with the specified ID. |
Operation | Optional Query Parameters | Description |
---|---|---|
DELETE /apikeys/{apikeyId} |
N/A | Deletes the API key with the specified ID. |
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/apikeys/AP1k3y1D3XamP13" \
-H 'Accept: application/json'
Application¶
Description
Application is a resource representing real-world application or integration with it’s own resources and limited access to tenants’ data. You can attach a Directory of Users to Application and use it to limit scope of operations for them.
Application URL
/applications/{applicationId}
Application Attributes
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
name |
String | 1 < N < 256 characters | Name of Application. |
createdAt |
String | RFC3339 Datetime | Indicates when this resource was created. |
updatedAt |
String | RFC3339 Datetime | Indicates when this resource’s attributes were last modified. |
official |
Boolean | N/A | Indicates whether it’s the official Application or not. Visible only for Api Key or offical User. |
status |
String (enum) | ENABLED , DISABLED |
Indicates whether Application is enabled or not. Visible only for Api Key or offical User. |
description |
String | N/A | The description of Application which may describes it’s purpose. |
custom |
Object | N/A | A custom structure you can store your own custom fields in. |
tenant |
Link | N/A | A link to a Tenant owning this Product. |
directory |
Link | N/A | A link to a Directory attached to this Application if exists. |
devices |
Link | N/A | A link to a Collection of all the Devices available in this Application (if requester is Api Key or offical User) or assigned to current User (if requester is User). |
clusters |
Link | N/A | A link to a Collection of all the Clusters created in this Application (if requester is Api Key or official User) or owned by current User (if requester is User). |
exports |
Link | N/A | A link to a Collection of all the Exports created for this Application. Visible only for Api Key or offical User. |
Application Example
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA",
"name": "Smart home application",
"createdAt": "2016-05-15T11:18:33Z",
"updatedAt": "2016-05-15T11:18:33Z",
"official": false,
"status": "ENABLED",
"description": "This application is our Smart Home app for end-users",
"custom": {
},
"tenant": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT"
},
"directory": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/directories/Som31D0fD1r3cTo"
},
"devices": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA/devices"
},
"clusters": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA/clusters"
},
"exports": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA/exports"
}
}
Application Operations¶
Operation | Attributes | Description |
---|---|---|
POST /tenants/{tenantId}/applications |
Required: name . Optional: description , custom , status , directory . |
Creates new application. |
Operation | Optional Query Parameters | Description |
---|---|---|
GET /applications/{applicationId} |
expand |
Retrieves the Application with the specified ID. Expandable links: devices , clusters , exports , tenant , directory . |
Operation | Attributes | Description |
---|---|---|
POST /applications/{applicationId} |
name , description , custom , status , directory |
Updates the Application with the specified ID. |
Operation | Optional Query Parameters | Description |
---|---|---|
DELETE /applications/{applicationId} |
N/A | Deletes the Application with the specified ID. |
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA" \
-H 'Accept: application/json'
It is possible to retrieve other independent resources using the Application for look-up.
Operation | Optional Query Parameters | Description |
---|---|---|
GET /applications/{applicationId}/{resourceName} |
Pagination, Sorting | Retrieves a collection of all of an Application’s associated resources of the specified type. Possible resource types are: devices , clusters and exports . |
Retrieving a Collection Associated with an Application
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA/clusters" \
-H 'Accept: application/json'
This query would retrieve a collection containing all the Clusters associated with the specified Application.
It is possible to retrieve subresources of Application
Operation | Optional Query Parameters | Description |
---|---|---|
GET /applications/{applicationId}/availableResources |
Pagination, Sorting | Retrieves a set of available in Application resources belonged to Application, Products, Clusters and Groups. |
Retrieving an available resources in Application
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA/resources" \
-H 'Accept: application/json'
Product¶
Description
Product is a model of your real-world product. You can create particular devices within it.
Product URL
/products/{productId}
Product Attributes
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
name |
String | 1 < N < 256 characters | Name of Product. |
createdAt |
String | RFC3339 Datetime | Indicates when this resource was created. |
updatedAt |
String | RFC3339 Datetime | Indicates when this resource’s attributes were last modified. |
properties |
Array(Object) | N/A | List of objects, each containing: key , name , setOn and unique. |
resources |
Object | N/A | An embedded object containing information about resources, containd data , events and commands arrays. |
extensions |
Object | N/A | An embedded object containing information available extensions and their configuration. |
custom |
Object | N/A | A custom structure you can store your own custom fields in. |
tenant |
Link | N/A | A link to a Tenant owning this Product. |
devices |
Link | N/A | A link to a Collection of all the Devices mapped to this Product. |
functions |
Link | N/A | A link to a Collection of all the Functions mapped to this Product. |
Product Example
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/products/Som31D0fpr0doocT",
"name": "Smart washing machine",
"createdAt": "2016-05-15T11:18:33Z",
"updatedAt": "2016-05-15T11:18:33Z",
"properties": [
{
"key": "macaddr",
"name": "MAC address",
"setOn": "MANUFACTURING",
"unique": true
}
],
"resources": {
"data": [
{
"id": "rpm",
"name": "Revolutions per minute",
"description": "Reports current RPM"
}
],
"events": [
{
"id": "dmg",
"name": "Machine damage",
"description": "Fired if machine damage occurred"
}
],
"commands": [
{
"id": "turn",
"name": "Turn washing",
"description": "Turns machine on/off",
"payloads": [
{
"name": "on",
"value": "ON"
},
{
"name": "off",
"value": "OFF"
}
]
}
]
},
"extensions": {
"connectors": {
"sigfox": {
"autoGenerate": true,
"contentType": "CUSTOM",
"parser": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/functions/SgKSGoEETgSQ0dpNgdA5Qg"
},
"status": "ENABLED"
}
}
},
"custom": {
},
"tenant": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT"
},
"devices": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/products/Som31D0fpr0doocT/devices"
},
"functions": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/products/Som31D0fpr0doocT/functions"
}
}
Product Operations¶
Operation | Attributes | Description |
---|---|---|
POST /tenants/{tenantId}/products |
Required: name . Optional: properties , resources , custom , extensions . |
Creates new product. |
Operation | Optional Query Parameters | Description |
---|---|---|
GET /products/{productId} |
expand |
Retrieves the Product with the specified ID. Expandable links: devices , functions , tenant . |
Operation | Attributes | Description |
---|---|---|
POST /products/{productId} |
name , properties , resources , custom , `extensions |
Updates the Product with the specified ID. |
Operation | Optional Query Parameters | Description |
---|---|---|
DELETE /products/{productId} |
N/A | Deletes the Product with the specified ID. |
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/products/Som31D0fpr0doocT" \
-H 'Accept: application/json'
It is possible to retrieve other independent resources using the Product for look-up.
Operation | Optional Query Parameters | Description |
---|---|---|
GET /products/{productId}/{resourceName} |
Pagination, Sorting | Retrieves a collection of all of a Product’s associated resources of the specified type. Possible resource types are: devices and functions . |
Retrieving a Collection Associated with a Product
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/products/Som31D0fpr0doocT/devices" \
-H 'Accept: application/json'
This query would retrieve a collection containing all the Devices associated with the specified Product.
Device¶
Description
Device is a single real-world node or other data source implementing Product model.
Device URL
/devices/{deviceId}
Device Attributes
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
token |
String | 32 characters | Device’s token. |
activated |
Boolean | N/A | Indicates whether device has been activated (by connecting with CloudThing platform). |
createdAt |
String | RFC3339 Datetime | Indicates when this resource was created. |
updatedAt |
String | RFC3339 Datetime | Indicates when this resource’s attributes were last modified. |
properties |
Object | N/A | Object with properties where key is a defined in Product property id. |
custom |
Object | N/A | A custom structure you can store your own custom fields in. |
tenant |
Link | N/A | A link to a Tenant owning this Product. |
product |
Link | N/A | A link to a Product this Device implements. |
Device Example
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/devices/Som31D0fd3V1c3",
"token": "STTPDGtpSNkGpHdasG1BznI0u7w9pK4p",
"createdAt": "2016-05-15T11:18:33Z",
"updatedAt": "2016-05-15T11:18:33Z",
"activated": true,
"custom": {
},
"properties": {
"macaddr": "00:11:22:33:44:55"
},
"tenant": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT"
},
"product": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/products/Som31D0fpr0doocT"
}
}
Device Operations¶
Operation | Attributes | Description |
---|---|---|
POST /products/{productId}/devices |
Optional: properties , custom . |
Creates new device. |
Operation | Optional Query Parameters | Description |
---|---|---|
GET /devices/{deviceId} |
expand |
Retrieves the Device with the specified ID. Expandable links: tenant , product . |
Operation | Attributes | Description |
---|---|---|
POST /devices/{deviceId} |
properties , custom |
Updates the Device with the specified ID. |
Operation | Optional Query Parameters | Description |
---|---|---|
DELETE /devices/{deviceId} |
N/A | Deletes the Device with the specified ID. |
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/devices/Som31D0fd3V1c3" \
-H 'Accept: application/json'
It is possible to use associated endpoint for retrieving additional data.
Operation | Optional Query Parameters | Description |
---|---|---|
GET /devices/{deviceId}/resources/{type}/{name} |
Pagination, Sorting | Retrieves a associated resource of the specified type. Possible resource types are: data , events and commands . |
POST /devices/{deviceId}/ownership |
n/a | Binds this device to current user (end-user only). token must be provided in request body. |
Retrieving a temperature measured by Device
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/devices/Som31D0fd3V1c3/resources/data/temp" \
-H 'Accept: application/json'
This query would retrieve a collection containing lat measurments of temp
resource by Device.
Claiming device ownership
curl -H "Authorization: Bearer {jwtToken}" -H 'Accept: application/json' \
-H 'Content-Type: application/json' -X POST -d '{"token":"t0k3N0fD3v1C3"}' \
"https://vanilla-ice.cloudthing.io/api/v1/devices/Som31D0fd3V1c3/ownership" \
This request would create bing between user and device.
Cluster¶
Description
Cluster is a container for devices which exists in separate context for every Application. Each Device can belong to only one Cluster per Application (eg. Cluster would represent a home or apartment in Smart Home project).
Cluster URL
/clusters/{clusterId}
Cluster Attributes
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
name |
String | 1 < N < 256 characters | Cluster’s name. |
description |
String | N/A | Description of Cluster. |
createdAt |
String | RFC3339 Datetime | Indicates when this resource was created. |
updatedAt |
String | RFC3339 Datetime | Indicates when this resource’s attributes were last modified. |
custom |
Object | N/A | A custom structure you can store your own custom fields in. |
tenant |
Link | N/A | A link to a Tenant owning this Product. |
application |
Link | N/A | A link to a Application this Cluster exists within. |
users |
Link | N/A | A link to a Collection of the Users who has rights to this Cluster. |
devices |
Link | N/A | A link to a Collection of the Devices which belongs to this Cluster. |
groups |
Link | N/A | A link to a Collection of the Groups existing within this Cluster. |
memberships |
Link | N/A | A link to a Collection of the Group Memberships associated with this Cluster. |
Cluster Example
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/clusters/c7UZt3Rs1DeX",
"name": "NYC apartment",
"description": "The Does family's New York City apartment",
"createdAt": "2016-05-15T11:18:33Z",
"updatedAt": "2016-05-15T11:18:33Z",
"custom": {
},
"tenant": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT"
},
"application": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/applications/AppL1CaT10n1D"
},
"users": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/clusters/c7UZt3Rs1DeX/users"
},
"devices": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/clusters/c7UZt3Rs1DeX/devices"
},
"groups": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/clusters/c7UZt3Rs1DeX/groups"
},
"memberships": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/clusters/c7UZt3Rs1DeX/memberships"
}
}
Cluster Operations¶
Operation | Attributes | Description |
---|---|---|
POST /applications/{applicationId}/clusters |
Optional: name , description , custom . |
Creates new Cluster. |
Operation | Optional Query Parameters | Description |
---|---|---|
GET /clusters/{clusterId} |
expand |
Retrieves the Cluster with the specified ID. Expandable links: tenant , application , users , devices , groups , memberships . |
Operation | Attributes | Description |
---|---|---|
POST /clusters/{clusterId} |
name , description , custom |
Updates the Cluster with the specified ID. |
Operation | Optional Query Parameters | Description |
---|---|---|
DELETE /clusters/{clusterId} |
N/A | Deletes the Cluster with the specified ID. |
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/clusters/c7UZt3Rs1DeX" \
-H 'Accept: application/json'
It is possible to retrieve other independent resources using the Cluster for look-up.
Operation | Optional Query Parameters | Description |
---|---|---|
GET /clusters/{clusterId}/{resourceName} |
Pagination, Sorting | Retrieves a collection of all of a Cluster’s associated resources of the specified type. Possible resource types are: devices , users`, ``groups and memberships . |
Retrieving a Collection Associated with a Cluster
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/clusters/c7UZt3Rs1DeX/devices" \
-H 'Accept: application/json'
This query would retrieve a collection containing all the Devices associated with the specified Cluster.
Cluster Membership¶
Description
Cluster Membership represents assignment of Device to Cluster.
Cluster Membership URL
/clusterMemberships/{membershipId}
Cluster Membership Attributes
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
createdAt |
String | RFC3339 Datetime | Indicates when this resource was created. |
updatedAt |
String | RFC3339 Datetime | Indicates when this resource’s attributes were last modified. |
device |
Link | N/A | A link to the Device this Cluster Membership is about. |
cluster |
Link | N/A | A link to the Cluster this Cluster Membership is about. |
Cluster Membership Example
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/clusterMemberships/Som31D0fMeM83rSh1P",
"createdAt": "2016-05-15T11:18:33Z",
"updatedAt": "2016-05-15T11:18:33Z",
"device": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/devices/d3v1C31dExa"
},
"cluster": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/clusters/cLUzT3r1DS0m3"
}
}
Cluster Membership Operations¶
Operation | Attributes | Description |
---|---|---|
POST /clusters/{clusterId}/memberships |
Required: device . |
Assigns given Device to Cluster. |
POST /devices/{deviceId}/clusterMemberships |
Required: cluster . |
Assigns Device to given Cluster. |
Operation | Optional Query Parameters | Description |
---|---|---|
GET /clusterMemberships/{membershipId} |
expand |
Retrieves the Cluster Membership with the specified ID. Expandable links: device , cluster . |
Operation | Optional Query Parameters | Description |
---|---|---|
DELETE /clusterMemberships/{membershipId} |
N/A | Deletes the Cluster Membership with the specified ID. |
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/clusterMemberships/Som31D0fMeM83rSh1P" \
-H 'Accept: application/json'
Group¶
Description
Group is a container for devices of the same Cluster. Each Device can belong to several Groups within one Cluster (eg. Group would represent a room in Smart Home project).
Group URL
/groups/{groupId}
Group Attributes
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
name |
String | 1 < N < 256 characters | Group’s name. |
description |
String | N/A | Description of Group. |
createdAt |
String | RFC3339 Datetime | Indicates when this resource was created. |
updatedAt |
String | RFC3339 Datetime | Indicates when this resource’s attributes were last modified. |
custom |
Object | N/A | A custom structure you can store your own custom fields in. |
tenant |
Link | N/A | A link to a Tenant owning this Group. |
application |
Link | N/A | A link to a Application this Group exists within. |
cluster |
Link | N/A | A link to a Cluster this Group exists within. |
devices |
Link | N/A | A link to a Collection of the Devices which belongs to this Group. |
Group Example
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/groups/gRoUp31xDeX",
"name": "Living room",
"description": "Living room in New York City apartment",
"createdAt": "2016-05-15T11:18:33Z",
"updatedAt": "2016-05-15T11:18:33Z",
"custom": {
},
"tenant": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT"
},
"application": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/applications/AppL1CaT10n1D"
},
"cluster": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/clusters/c7UZt3Rs1DeX"
},
"devices": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/groups/gRoUp31xDeX/devices"
}
}
Group Operations¶
Operation | Attributes | Description |
---|---|---|
POST /clusters/{clusterId}/groups |
Optional: name , description , custom . |
Creates new Group. |
Operation | Optional Query Parameters | Description |
---|---|---|
GET /groups/{groupId} |
expand |
Retrieves the Group with the specified ID. Expandable links: tenant , application , cluster , devices . |
Operation | Attributes | Description |
---|---|---|
POST /groups/{groupId} |
name , description , custom |
Updates the Group with the specified ID. |
Operation | Optional Query Parameters | Description |
---|---|---|
DELETE /groups/{groupId} |
N/A | Deletes the Group with the specified ID. |
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/groups/gRoUp31xDeX" \
-H 'Accept: application/json'
It is possible to retrieve other independent resources using the Group for look-up.
Operation | Optional Query Parameters | Description |
---|---|---|
GET /groups/{groupId}/{resourceName} |
Pagination, Sorting | Retrieves a collection of all of a Group’s associated resources of the specified type. Possible resource types are: devices . |
Retrieving a Collection Associated with a Group
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/groups/gRoUp31xDeX/devices" \
-H 'Accept: application/json'
This query would retrieve a collection containing all the Devices associated with the specified Group.
Group Membership¶
Description
Group Membership represents assignment of Device to Group.
Group Membership URL
/groupMemberships/{membershipId}
Group Membership Attributes
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
createdAt |
String | RFC3339 Datetime | Indicates when this resource was created. |
updatedAt |
String | RFC3339 Datetime | Indicates when this resource’s attributes were last modified. |
device |
Link | N/A | A link to the Device this Group Membership is about. |
group |
Link | N/A | A link to the Group this Group Membership is about. |
Group Membership Example
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/groupMemberships/Som31D0fMeM83rSh1P",
"createdAt": "2016-05-15T11:18:33Z",
"updatedAt": "2016-05-15T11:18:33Z",
"device": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/devices/d3v1C31dExa"
},
"group": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/groups/gRooP1DS0m3"
}
}
Group Membership Operations¶
Operation | Attributes | Description |
---|---|---|
POST /groups/{groupId}/memberships |
Required: device . |
Assigns given Device to Group. |
POST /devices/{deviceId}/groupMemberships |
Required: group . |
Assigns Device to given Group. |
Operation | Optional Query Parameters | Description |
---|---|---|
GET /groupMemberships/{membershipId} |
expand |
Retrieves the Group Membership with the specified ID. Expandable links: device , group . |
Operation | Optional Query Parameters | Description |
---|---|---|
DELETE /groupMemberships/{membershipId} |
N/A | Deletes the Group Membership with the specified ID. |
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/groupMemberships/Som31D0fMeM83rSh1P" \
-H 'Accept: application/json'
Export¶
Description
Export represents access level for different resources granted to Application .
Export URL
/exports/{exportId}
Export Attributes
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
createdAt |
String | RFC3339 Datetime | Indicates when this resource was created. |
updatedAt |
String | RFC3339 Datetime | Indicates when this resource’s attributes were last modified. |
modelType |
String (enum) | DEVICE , GROUP , CLUSTER |
Type of exported resource owner. |
product |
Link | N/A | A link to a Product if modelType is DEVICE . |
limitsType |
String (enum) | DEVICE , GROUP , CLUSTER |
Type of container limiting exporting resources. |
limits |
Link | N/A | A link to a Device if limitsType is DEVICE , a Group if limitsType is GROUP or a Cluster if limitsType is CLUSTER . |
export |
Array (Object) | N/A | An array of objects defining exported resources. |
tenantExportingPermission |
String (enum) | PRIMARY , EXPORT |
Indicates wheter exporting Tenant has a primary permission for this resource or imported it. |
tenantExporting |
Link | N/A | A link to a Tenant owning this Product. |
application |
Link | N/A | A link to a Application importing this Export. |
Export Example
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/exports/3xP0rT1D1234",
"modelType": "DEVICE",
"createdAt": "2016-05-15T11:18:33Z",
"updatedAt": "2016-05-15T11:18:33Z",
"product": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/products/Som31D0fpR0do0cT"
},
"limitsType": "CLUSTER",
"limits": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/clusters/cLo0zt3rz1D"
},
"export": [
{
"type": "DATA",
"name": "temp",
"read": true,
"write": true,
"grantRead": false,
"grantWrite": false
},
{
"type": "COMMAND",
"name": "turn",
"read": true,
"write": true,
"grantRead": true,
"grantWrite": false
},
{
"type": "PROPERTY",
"name": "macaddr",
"read": true,
"write": false,
"grantRead": false,
"grantWrite": false
}
],
"tenantExportingPermission": "PRIMARY",
"tenantExporting": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT"
},
"application": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/applications/aPpl1Cat10n1D"
}
}
Export Operations¶
Operation | Attributes | Description |
---|---|---|
POST /applications/{applicationId}/exports |
Required: modelType , export , tenantExportingPermission . Required if modelType is DEVICE : product . Optional: limitsType , limits . |
Creates new Export. |
Operation | Optional Query Parameters | Description |
---|---|---|
GET /exports/{exportId} |
expand |
Retrieves the Export with the specified ID. Expandable links: product , limits , application , tenantExporting . |
Operation | Attributes | Description |
---|---|---|
POST /exports/{exportId} |
modelType , export , product , limitsType , limits |
Updates the Export with the specified ID. |
Operation | Optional Query Parameters | Description |
---|---|---|
DELETE /exports/{exportId} |
N/A | Deletes the Export with the specified ID. |
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/exports/3xP0rT1D1234" \
-H 'Accept: application/json'
Firmware¶
Description
Firmware represents binary firmware file for devices
Firmware URL
/firmwares/{firmwareId}
Firmware Attributes
Attribute | Type | Valid Value(s) | Description |
---|---|---|---|
href |
Link | N/A | The resource’s fully qualified location URL. |
createdAt |
String | RFC3339 Datetime | Indicates when this resource was created. |
updatedAt |
String | RFC3339 Datetime | Indicates when this resource’s attributes were last modified. |
size |
Number | >0 | Size of firmware image. |
md5 |
String | N/A | A md5 sum of firmware image. |
module |
String | N/A | Name of the module firmware image is valid for. |
version |
String | N/A | Version of firmware image. |
product |
Link | N/A | A link to a Product this Firmware is associated with. |
tenant |
Link | N/A | A link to a Tenant owning this Firmware. |
Firmware Example
{
"href": "https://vanilla-ice.cloudthing.io/api/v1/firmwares/3xP0rT1D1234",
"createdAt": "2016-05-15T11:18:33Z",
"updatedAt": "2016-05-15T11:18:33Z",
"product": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/products/Som31D0fpR0do0cT"
},
"size": 1445864,
"md5": "4de8a06df40a257e31263c11be12d77a",
"module": "rootfs",
"version": "v1.3.7",
"tenant": {
"href": "https://vanilla-ice.cloudthing.io/api/v1/tenants/Som31D0fT3NAnT"
}
}
Firmware Operations¶
Operation | Attributes | Description |
---|---|---|
POST /products/{productId}/firmwares |
Required: module , version . |
Creates new Firmware. |
POST /firmwares/{firmwareId}/blob |
Content-Type: multipart/form-data , Required: file . |
Uploads new Firmware image. |
Operation | Optional Query Parameters | Description |
---|---|---|
GET /firmwares/{firmwareId} |
expand |
Retrieves the Firmware with the specified ID. Expandable links: product , tenant . |
GET /firmwares/{firmwareId}/blob |
N/A | Downloads Firmware image. |
Operation | Attributes | Description |
---|---|---|
POST /firmwares/{firmwareId} |
module , version |
Updates the Firmware with the specified ID. |
Operation | Optional Query Parameters | Description |
---|---|---|
DELETE /firmwares/{firmwareId} |
N/A | Deletes the Firmware with the specified ID. |
curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/exports/3xP0rT1D1234" \
-H 'Accept: application/json'