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

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
Methods
Serialization format
TLS
Authentication & authorization
- Basic auth
- JWT token auth
Collections
Linking & expanding

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.

Basic auth ¶

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`

JWT token auth ¶

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 ¶

Tenant Operations
- Retrieve A Tenant
- Using A Tenant for Look-Up

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 ¶

Retrieve A Tenant ¶

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.

Example Query¶

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'

Using A Tenant for Look-Up ¶

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`.

Example Queries¶

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 ¶

Directory Operations

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 ¶

Create A Directory ¶

Operation	Attributes	Description
`POST /tenants/{tenantId}/directories`	Required: `name`. Optional: `description`, `custom`.	Creates new directory.

Retrieve A Directory ¶

Operation	Optional Query Parameters	Description
`GET /directories/{directoryId}`	`expand`	Retrieves the Directory with the specified ID. Expandable links: `users`, `usergroups`, `applications`, `tenant`.

Update A Directory ¶

Operation	Attributes	Description
`POST /directories/{directoryId}`	`name`, `description`, `custom`	Updates the Directory with the specified ID.

Delete A Directory ¶

Operation	Optional Query Parameters	Description
`DELETE /directories/{directoryId}`	N/A	Deletes the Directory with the specified ID.

Example Query¶

curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/directories/Som31D0fD1r3cTo" \
-H 'Accept: application/json'

Using A Directory for Look-Up ¶

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`.

Example Queries¶

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 ¶

Usergroup Operations

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 ¶

Create A Usergroup ¶

Operation	Attributes	Description
`POST /directories/{directoryId}/usergroups`	Required: `name`. Optional: `custom`.	Creates new usergroup.

Retrieve A Usergroup ¶

Operation	Optional Query Parameters	Description
`GET /usergroups/{usergroupId}`	`expand`	Retrieves the Usergroup with the specified ID. Expandable links: `users`, `memberships`, `directory`, `tenant`.

Update A Usergroup ¶

Operation	Attributes	Description
`POST /usergroups/{usergroupId}`	`name`, `custom`	Updates the Usergroup with the specified ID.

Delete A Usergroup ¶

Operation	Optional Query Parameters	Description
`DELETE /usergroups/{usergroupId}`	N/A	Deletes the Usergroup with the specified ID.

Example Query¶

curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/usergroups/Som31D0fOoZ3rGru" \
-H 'Accept: application/json'

Using A Usergroup for Look-Up ¶

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`.

Example Queries¶

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 ¶

User Operations

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 ¶

Create A User ¶

Operation	Attributes	Description
`POST /directories/{directoryId}/users`	Required: `email`, `password`. Optional: `firstName`, `surname`, `custom`.	Creates new user.

Retrieve A 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`.

Update A User ¶

Operation	Attributes	Description
`POST /users/{userId}`	`email`, `password`, `firstName`, `surname`, `custom`	Updates the User with the specified ID.

Delete A User ¶

Operation	Optional Query Parameters	Description
`DELETE /users/{userId}`	N/A	Deletes the User with the specified ID.

Example Query¶

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'

Using A User for Look-Up ¶

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`.

Example Queries¶

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 ¶

Membership Operations

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 ¶

Create A Membership ¶

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.

Retrieve A Membership ¶

Operation	Optional Query Parameters	Description
`GET /memberships/{membershipId}`	`expand`	Retrieves the Membership with the specified ID. Expandable links: `user`, `usergroup`.

Delete A Membership ¶

Operation	Optional Query Parameters	Description
`DELETE /memberships/{membershipId}`	N/A	Deletes the Membership with the specified ID.

Example Query¶

curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/memberships/Som31D0fMeM83rSh1P" \
-H 'Accept: application/json'

API Key ¶

API key Operations

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 ¶

Create An API key ¶

Operation	Attributes	Description
`POST /tenants/{tenantId}/apikeys`	Optional: `name`, `description`, `custom`, `status`.	Creates new API key.

Retrieve An API key ¶

Operation	Optional Query Parameters	Description
`GET /apikeys/{apikeyId}`	`expand`	Retrieves the API key with the specified ID. Expandable links: `tenant`.

Update An API key ¶

Operation	Attributes	Description
`POST /apikeys/{apikeyId}`	`name`, `description`, `custom`, `status`	Updates the API key with the specified ID.

Delete An API key ¶

Operation	Optional Query Parameters	Description
`DELETE /apikeys/{apikeyId}`	N/A	Deletes the API key with the specified ID.

Example Query¶

curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/apikeys/AP1k3y1D3XamP13" \
-H 'Accept: application/json'

Application ¶

Application Operations

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 ¶

Create An Application ¶

Operation	Attributes	Description
`POST /tenants/{tenantId}/applications`	Required: `name`. Optional: `description`, `custom`, `status`, `directory`.	Creates new application.

Retrieve An Application ¶

Operation	Optional Query Parameters	Description
`GET /applications/{applicationId}`	`expand`	Retrieves the Application with the specified ID. Expandable links: `devices`, `clusters`, `exports`, `tenant`, `directory`.

Update An Application ¶

Operation	Attributes	Description
`POST /applications/{applicationId}`	`name`, `description`, `custom`, `status`, `directory`	Updates the Application with the specified ID.

Delete An Application ¶

Operation	Optional Query Parameters	Description
`DELETE /applications/{applicationId}`	N/A	Deletes the Application with the specified ID.

Example Query¶

curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/applications/Som31D0faPpl1cA" \
-H 'Accept: application/json'

Using An Application for Look-Up ¶

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`.

Example Queries¶

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.

Associated subresources of 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.

Example Queries¶

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 ¶

Product Operations

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 ¶

Create A Product ¶

Operation	Attributes	Description
`POST /tenants/{tenantId}/products`	Required: `name`. Optional: `properties`, `resources`, `custom`, `extensions`.	Creates new product.

Retrieve A Product ¶

Operation	Optional Query Parameters	Description
`GET /products/{productId}`	`expand`	Retrieves the Product with the specified ID. Expandable links: `devices`, `functions`, `tenant`.

Update A Product ¶

Operation	Attributes	Description
`POST /products/{productId}`	`name`, `properties`, `resources`, `custom`, `extensions	Updates the Product with the specified ID.

Delete A Product ¶

Operation	Optional Query Parameters	Description
`DELETE /products/{productId}`	N/A	Deletes the Product with the specified ID.

Example Query¶

curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/products/Som31D0fpr0doocT" \
-H 'Accept: application/json'

Using A Product for Look-Up ¶

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`.

Example Queries¶

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 ¶

Device Operations

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 ¶

Create A Device ¶

Operation	Attributes	Description
`POST /products/{productId}/devices`	Optional: `properties`, `custom`.	Creates new device.

Retrieve A Device ¶

Operation	Optional Query Parameters	Description
`GET /devices/{deviceId}`	`expand`	Retrieves the Device with the specified ID. Expandable links: `tenant`, `product`.

Update A Device ¶

Operation	Attributes	Description
`POST /devices/{deviceId}`	`properties`, `custom`	Updates the Device with the specified ID.

Delete A Device ¶

Operation	Optional Query Parameters	Description
`DELETE /devices/{deviceId}`	N/A	Deletes the Device with the specified ID.

Example Query¶

curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/devices/Som31D0fd3V1c3" \
-H 'Accept: application/json'

Associated endpoints ¶

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.

Example Queries¶

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 ¶

Cluster Operations

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 ¶

Create A Cluster ¶

Operation	Attributes	Description
`POST /applications/{applicationId}/clusters`	Optional: `name`, `description`, `custom`.	Creates new Cluster.

Retrieve A 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`.

Update A Cluster ¶

Operation	Attributes	Description
`POST /clusters/{clusterId}`	`name`, `description`, `custom`	Updates the Cluster with the specified ID.

Delete A Cluster ¶

Operation	Optional Query Parameters	Description
`DELETE /clusters/{clusterId}`	N/A	Deletes the Cluster with the specified ID.

Example Query¶

curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/clusters/c7UZt3Rs1DeX" \
-H 'Accept: application/json'

Using A Cluster for Look-Up ¶

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`.

Example Queries¶

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 ¶

Cluster Membership Operations

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 ¶

Create A Cluster Membership ¶

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.

Retrieve A Cluster Membership ¶

Operation	Optional Query Parameters	Description
`GET /clusterMemberships/{membershipId}`	`expand`	Retrieves the Cluster Membership with the specified ID. Expandable links: `device`, `cluster`.

Delete A Cluster Membership ¶

Operation	Optional Query Parameters	Description
`DELETE /clusterMemberships/{membershipId}`	N/A	Deletes the Cluster Membership with the specified ID.

Example Query¶

curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/clusterMemberships/Som31D0fMeM83rSh1P" \
-H 'Accept: application/json'

Group ¶

Group Operations

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 ¶

Create A Group ¶

Operation	Attributes	Description
`POST /clusters/{clusterId}/groups`	Optional: `name`, `description`, `custom`.	Creates new Group.

Retrieve A Group ¶

Operation	Optional Query Parameters	Description
`GET /groups/{groupId}`	`expand`	Retrieves the Group with the specified ID. Expandable links: `tenant`, `application`, `cluster`, `devices`.

Update A Group ¶

Operation	Attributes	Description
`POST /groups/{groupId}`	`name`, `description`, `custom`	Updates the Group with the specified ID.

Delete A Group ¶

Operation	Optional Query Parameters	Description
`DELETE /groups/{groupId}`	N/A	Deletes the Group with the specified ID.

Example Query¶

curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/groups/gRoUp31xDeX" \
-H 'Accept: application/json'

Using A Group for Look-Up ¶

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`.

Example Queries¶

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 ¶

Group Membership Operations

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 ¶

Create A Group Membership ¶

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.

Retrieve A Group Membership ¶

Operation	Optional Query Parameters	Description
`GET /groupMemberships/{membershipId}`	`expand`	Retrieves the Group Membership with the specified ID. Expandable links: `device`, `group`.

Delete A Group Membership ¶

Operation	Optional Query Parameters	Description
`DELETE /groupMemberships/{membershipId}`	N/A	Deletes the Group Membership with the specified ID.

Example Query¶

curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/groupMemberships/Som31D0fMeM83rSh1P" \
-H 'Accept: application/json'

Export ¶

Export Operations

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 ¶

Create An Export ¶

Operation	Attributes	Description
`POST /applications/{applicationId}/exports`	Required: `modelType`, `export`, `tenantExportingPermission`. Required if `modelType` is `DEVICE`: `product`. Optional: `limitsType`, `limits`.	Creates new Export.

Retrieve An Export ¶

Operation	Optional Query Parameters	Description
`GET /exports/{exportId}`	`expand`	Retrieves the Export with the specified ID. Expandable links: `product`, `limits`, `application`, `tenantExporting`.

Update An Export ¶

Operation	Attributes	Description
`POST /exports/{exportId}`	`modelType`, `export`, `product`, `limitsType`, `limits`	Updates the Export with the specified ID.

Delete An Export ¶

Operation	Optional Query Parameters	Description
`DELETE /exports/{exportId}`	N/A	Deletes the Export with the specified ID.

Example Query¶

curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/exports/3xP0rT1D1234" \
-H 'Accept: application/json'

Firmware ¶

Firmware Operations

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 ¶

Create A Firmware ¶

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.

Retrieve A Firmware ¶

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.

Update A Firmware ¶

Operation	Attributes	Description
`POST /firmwares/{firmwareId}`	`module`, `version`	Updates the Firmware with the specified ID.

Delete A Firmware ¶

Operation	Optional Query Parameters	Description
`DELETE /firmwares/{firmwareId}`	N/A	Deletes the Firmware with the specified ID.

Example Query¶

curl -u "user@example.com:password" \
"https://vanilla-ice.cloudthing.io/api/v1/exports/3xP0rT1D1234" \
-H 'Accept: application/json'

Welcome to CloudThing’s documentation!¶

General Concept¶

Getting Started¶

CloudThing APIs¶

Connectors APIs¶

General¶

Serialization formats¶

MQTT API¶

HTTP API¶

CoAP API¶

Sigfox¶

The Things Network¶

LoRaWAN networks¶

Application APIs¶

HTTP REST API Reference¶

MQTT Pub/Sub API Reference¶

Indices and tables¶