Filter results by

REST and WebSockets

This is an overview of how your devices and applications can send and receive messages on ARTIK Cloud, using both REST and WebSocket APIs. Using this information, you will be able to post messages to ARTIK Cloud, retrieve historical data, and use WebSockets to set up a real-time data stream. When sending messages via REST or WebSocket, you can also put Actions in messages so that destination devices can perform the specified Actions.

Any message sent to ARTIK Cloud may not be bigger than 1 KB.

You can use the Device Simulator to simulate sending messages and Actions to ARTIK Cloud via REST and WebSockets.

REST API

With ARTIK Cloud's REST API, you can send and retrieve historical data according to a specific timestamp or range. This allows you to perform analytics on various scenarios and contexts. You also can send Actions to ARTIK Cloud, which will be routed to the destination device to perform these Actions.

Posting a message

POST /messages

When sending a message that contains only data and no Actions, only the source device ID (sdid) and payload are required. The type field defaults to value "message". However, we strongly suggest that you explicitly set type to message so that your app is future-proof.

Using the timestamp parameter (ts), you can specify a timestamp for the message in milliseconds. Values up to the current server timestamp grace period are valid. If you omit ts, the message defaults to the current time.

Example Request

1
2
3
4
5
6
{
  "sdid": "HIuh2378jh",
  "ts": 1388179812427,
  "type": "message",
  "data": [payload]
}           

You'll then receive a message ID (mid) that you can use to query this message in other calls:

Example response

1
2
3
4
5
{
  "data": {
    "mid": "7fb20d3809b54075af6bdfc22591c521"
  }
}     

You cannot send a message with type as "message" to another device even if you include the destination device ID (ddid). The destination device won't receive this message. However you can send a message with Actions to an device.

Posting a message with Actions

POST /messages

When sending a message with Actions, you must include the destination device ID (ddid) and a payload that contains Actions. In addition, you must set the value of type to "action". By default, its value is "message". The source device ID (sdid) is optional.

Example Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "ddid": "9f06411ad3174a4f98444a374447fe10",
  "ts": 1388179812427,
  "type": "action",
  "data": {
    "actions": [
      {
        "name": "setOn",
        "parameters": {}
      },
      {
        "name": "setColorRGB",
        "parameters": {
          "colorRGB": {
              "r": 192,
              "g": 180,
              "b": 45
          },
          "intensity": 55
        }
      }
    ]
  }
}

In the above example, the message contains two Actions, setOn and setColorRGB. You'll then receive a response that is similar to the response of a message that does not contain Actions.

Any message with Actions should only contain "actions" in the payload.

Getting normalized messages

With this call, you can use different URL query parameter combinations to get historical data by message ID or by device.

GET /messages

Get by message ID

Parameter Description
mid The ARTIK Cloud message ID being searched.
uid (Optional) user ID of a user who has granted read access. If not specified, this defaults to the current authenticated user.

Get by device

Parameter Description
sdid Source device ID of the messages being searched.
startDate Time of earliest item to return (milliseconds since epoch).
endDate Time of latest item to return (milliseconds since epoch).

Common parameters include order to specify the sort order (based on ts, message timestamp from source), count to specify the number of items to return, and offset, a string required for pagination. See the API reference for more information and parameter combinations.

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "uid":"10022",
  "sdid":"cf1b01690f7c41df80e01482c6246a6e",
  "order": "asc",
  "startDate": 1,
  "endDate": 1402434042000,
  "count": 1,
  "size": 1,
  "offset": "",
  "next": "",
  "data": [
    {
      "sdtid": "dt6172aca4919f40a4a96afbd27cee09c8",
      "sdid":"cf1b01690f7c41df80e01482c6246a6e",
      "data": {
        "state": "off"
      },
      "mid": "80bff72064614fd5b5b05cb66c1ccfda",
      "ts": 1377303199000,
      "cts": 1377303199000,
      "uid": "10022"
    }
  ]
}    

Getting last normalized messages

This is a simple way to retrieve the most recent messages sent by devices. You must include as query parameters count to specify the number of items to return, and sdids to specify at least one source device ID. You may include more than one source device ID in a comma-separated list.

GET /messages/last

Getting message snapshots

Use this call to get a quick view of the current device state. The device "state" refers to the last received value for each field declared in the device type Manifest. Each message sent by a device can contain all or a subset of these fields. Pass a comma-separated list of sdids in the URL query string to return a snapshot of each device state.

GET /messages/snapshots

Live-streaming data with WebSocket API

By using WebSockets, you can set up a connection between ARTIK Cloud and compatible devices or applications to receive and/or send messages in real-time.

There are three types of WebSockets: Firehose, event feed, and device channel. Your application uses a Firehose WebSocket to listen to messages sent by the source devices that the application monitors. It would likewise use an event feed to receive updates on the status of devices, such as when they are enabled, modified, or deleted.

You would use a device channel WebSocket to receive messages targeted to your applications or devices. The device channel WebSocket also allows the applications or devices to send messages back to ARTIK Cloud.

Firehose WebSocket

WebSocket /live

The Firehose WebSocket is primarily used by applications with monitoring functionalities. This call sets up a one-directional data connection from ARTIK Cloud to a WebSocket client. The application, as the client, listens in real-time for any new messages sent to ARTIK Cloud by the specified source devices.

Messages received at this WebSocket endpoint are not necessarily ordered based on the ts field.

Request parameters

Parameter Description
Authorization Access token (user, device, or application token)
sdids (Optional) Comma-separated list of source device IDs. Accepts a single device ID.
sdtids (Optional) Comma-separated list of source device type IDs. Accepts a single device type ID.
uid (Optional) User ID of the target stream.
includeSharedDevices (Optional) Boolean (true/false). Include shared devices (default: false). Only applies when connecting per user (with uid).

You can use different URL query parameter combinations to get messages by device, by device type, or by user.

Combination Required Parameters
Get by devices sdids, Authorization
Get by device type sdtids, Authorization
Get by user uid, Authorization

We do not support "Get by device type" when a device token is provided as the access token.

For better performance, we suggest being as specific as possible when passing API call parameters. For example, the "Get by devices" combination returns the result more quickly than the "Get by user" combination.

In the following example we use Tyrus, a Java API for WebSockets suitable for web applications. We listen to the messages sent to ARTIK Cloud by the two source devices. In this specific example, the provided access token could be an application token or a user token.

Example

1
java -jar tyrus-client-cli-1.3.3.jar "wss://api.artik.cloud/v1.1/live?sdids=12345,6789&uid=10022&Authorization=bearer+1c20060d9b9f4ad09ee16919a45c71b7"

In the below example, the client receives a copy of the message that one of the source devices sends to ARTIK Cloud.

Example message received by client

1
2
3
4
5
6
7
8
9
10
11
{
  "sdtid":"nike_fuelband",
  "data":{
    "stepCount":5000
  },
  "mid":"c7f88d4367394fb696eee413666c83d9",
  "ts":1377793344153,
  "cts":1377793344153,
  "uid":"10022",
  "sdid":"12345"
} 

Ping

ARTIK Cloud sends a ping every 30 seconds to the client. If a ping is not received, the connection has stalled and the WebSocket client must reconnect.

Example ping message sent by server

1
2
3
{
  "type": "ping"
}         

Event feed WebSocket

WebSocket /events

Like the Firehose WebSocket, this call sets up a one-directional data connection from ARTIK Cloud to a WebSocket client. The application, as the client, listens in real-time for events sent to ARTIK Cloud that pertain to the specified source devices.

Request parameters

Parameter Description
authorization Access token (user, device, or application token)
uid (Optional) User ID of the target stream. If not specified, the uid implied in the access token is assumed.
did (Optional) Device ID for which to receive events.
dids (Optional) Comma-separated list of device IDs. Specifies a list of devices for which to receive events.
events (Optional) Comma-separated list of event names or event names with wildcard (e.g., device.*, user.profile.updated). If not specified, events = * is assumed.

Supported events

Event name Description Occurs when
device.new A new device has been created. After a device is created in My ARTIK Cloud or using the POST /devices API.
device.connected A device has been enabled. After device.new (since it is enabled by default), or when device is switched back from disconnected state using the PUT /devices/<deviceID> API.
device.updated A device has been modified. After a device was modified in My ARTIK Cloud or using the PUT /devices/<deviceID> API.
device.disconnected A device has been disabled. After a device has been marked as disabled using the PUT /devices/<deviceID> API and before device.deleted.
device.deleted A device has been deleted. After a device is deleted from My ARTIK Cloud or using the DELETE /devices/<deviceID> API.
user.profile.updated A user's profile has been modified. After the user's profile information is changed.
device.status.online A device went online. After a device makes an active connection to an API with presence support (WebSockets, MQTT, CoAP), or when it gets a ping while actively connected.
device.status.offline A device went offline. After a device succesfully closes active connection from ARTIK Cloud (WebSockets, MQTT, CoAP), or the platform reports the active connection to the client was lost.

The behavior of device.status.online may be changed in the future.

Examples of event feeds

Listen for all supported events for a user ID:

1
wss://api.artik.cloud/v1.1/events?authorization=bearer+6fb02e864c1247ad9c3fcfeb5a94f913&uid=4ece85e077c945ebbdd3d0613ab659c0

Listen for all supported events pertaining to a device:

1
wss://api.artik.cloud/v1.1/events?authorization=bearer+6fb02e864c1247ad9c3fcfeb5a94f913&did=38d3590f705b461f8b4c71a6da80ff31&events=device.*

Listen for update and deletion events for a device:

1
wss://api.artik.cloud/v1.1/events?authorization=bearer+6fb02e864c1247ad9c3fcfeb5a94f913&did=38d3590f705b461f8b4c71a6da80ff31&events=device.updated,device.deleted

Listen for presence events (reported online and offline status) for a device:

1
wss://api.artik.cloud/v1.1/events?authorization=bearer+6fb02e864c1247ad9c3fcfeb5a94f913&uid=4ece85e077c945ebbdd3d0613ab659c0&dids=38d3590f705b461f8b4c71a6da80ff31,37a3475b9e284ae18d98f1071e691753&events=device.status.*

Example output

Below are examples of the JSON returned for events pertaining to the example device ID 38d3590f705b461f8b4c71a6da80ff31 used above.

The device just went online (via WebSockets, MQTT, or CoAP), or got a PING while actively connected:

1
2
3
4
5
6
7
8
{
  "event":"device.status.online",
  "ts":1475521086554,
  "data":{
    "uid":"4ece85e077c945ebbdd3d0613ab659c0", // Owner of the device
    "did":"38d3590f705b461f8b4c71a6da80ff31" // Device that is actively connected
  }
}

The device was deleted:

1
2
3
4
5
6
7
8
9
10
{
  "event": "device.deleted",
  "ts": 1475521114668,
  "data": {
    "uid": "4ece85e077c945ebbdd3d0613ab659c0", // Owner of the device
    "aid": "068fa23cc68b40bbb9df68ff24b3de5e", // Application ID through which the device was deleted
    "did": "38d3590f705b461f8b4c71a6da80ff31", // Device that was deleted
    "dtid": "dtf9d52ea094424f4da00d802aa9ec856e" // Device's device type ID
  }
}

Device channel WebSocket

Setting up a device channel WebSocket

This call opens a data connection between ARTIK Cloud and a device or device list.

A device can only maintain at most one persistent connection with ARTIK Cloud with its device token.

Specifically, the restriction is reinforced for the connection using one of the following endpoints:

WebSocket: /websocket
MQTT: /v1.1/messages/ and /v1.1/actions/
CoAP: /v1.1/actions/

WebSocket /websocket

Setting ack to true in the above URL query string will cause ARTIK Cloud to return an ACK message for each message sent. Otherwise, this defaults to false and you will not receive ACK messages.

All client applications, including device proxies, must register after opening the connection. Otherwise client messages will be discarded and clients will not be sent messages.

If the client app does not register within 30 seconds of opening the connection, the WebSocket will be closed automatically.

The registration message type must be register. Authorization refers to the authorization token with READ and WRITE access to sdid. The cid parameter is discussed in Sending messages.

Example registration message sent by client

1
2
3
4
5
6
{
  "sdid": "DFKK234-JJO5",
  "Authorization": "bearer d77054a9b0874ba884499eef7768b7b9",
  "type": "register",
  "cid": "1234567890"
}         

Example ACK message

1
2
3
4
5
6
7
{
  "data":{
    "message":"OK",
    "code":"200",
    "cid":"1234567890"
  }
}

You can send multiple messages to register more than one device. Then you can send and receive messages for these devices over a single device channel WebSocket.

Managing the device channel WebSocket

You can send a message of type=list to return an array of devices currently registered on the device channel WebSocket. They will be listed by sdid.

A message of type=unregister will unregister a device and remove it from the list of registered devices. Note that if the last remaining device on the WebSocket is unregistered, the WebSocket connection will be disconnected.

See the WebSockets API reference for details about listing registered devices and unregistering devices.

As with /live, ARTIK Cloud sends a ping every 30 seconds to the client. If a ping is not received, the connection has stalled and the client must reconnect.

Sending messages

You can send a message with

  • type as "message" to ARTIK Cloud.
  • type as "action" to another device. You must specify ddid in your request.

Additionally, if ack was set to "true" when opening the WebSocket connection, you may optionally include cid—the client ID. ARTIK Cloud will return cid (in addition to mid) in its ACK messages to facilitate client side validations. This helps to clarify which response is for which message.

The example request at Posting a message with Actions shows how Actions are formatted in a message.

In the following example, sdid refers to the device ID of the device registered on the device channel WebSocket.

Example request

1
2
3
4
5
6
7
8
{
  "sdid": "DFKK234-JJO5",
  "cid":"1234567890", 
  "type": "message",
  "data":{
    "someField": "someValue"
  }
}

Example ACK message

1
2
3
4
5
6
{
  "data":{
    "mid": "6d002024824746649766743582c9f005", 
    "cid": "1234567890"
  }
}

Receiving messages

In the below example, ddid refers to the device ID of the device connected to the WebSocket. Connected devices will receive messages that contain their corresponding ddid and have type as "action".

A destination device must be connected to ARTIK Cloud via a device channel WebSocket in order to receive Actions in real-time.

Example message received by client

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "ddid": "<destination device ID = this client device ID>",
  "mid": "<message ID>",
  "type": "action",
  "data": {
    "actions": [
      {
        "name": "setOn",
        "parameters": {}
      }
    ]
  }
}     

See the API reference for a list of WebSocket errors.

Message quotas

Each pricing plan includes a limit to the number of messages that can be sent by a device per day. Once the quota has been reached, messages from that device will be rejected.

Message quotas apply to message type messages only. There are two instances in which messages do not count toward the daily message quota:

  • Actions sent/received by a device do not count toward the quota.
  • Messages rejected at the public API (e.g., for exceeded payload size, missing metadata, or invalid authentication/authorization) do not count toward the quota.

Quota error codes are documented in the API reference.

Note that message quotas are separate from message rate limits.