RealTime.io Web Client API for Iota Devices

Overview

The RealTime.io Web Client API for Iota Devices is a suite of API requests that allows developers to interact with Iota-enabled devices connected to RealTime.io web servers. This API requires a RealTime.io / ioBridge.com user account, RealTime.io API Keys, and Iota-enabled Devices.

API Info

API Versions

v1.0

  • Initial release

API Definitions

The following keywords and phrases are used with the RealTime.io technology and supporting APIs.

RealTime.io

The cloud server that acts as the connection hub for all devices and API requests.

HTTP GET

A method to request data from a server by a client. HTTP GETs are made to a URI/URL and usually contain Query String Parameters.

HTTP POST

A method to send data from a client to a server. HTTP POSTs have a header and a body. The header typically contains the URI/URL of the server and the content type. The body of the HTTP POST contains the data that you are sending to the server. In terms of RealTime.io, the client is the Application and the server is the RealTime.io server.

Device

Embedded hardware capable of connecting to the RealTime.io cloud server.

Serial Number

A unique 16 character key that identifies a device. Valid characters are 0-9, A-F.

API Key

A unique key that masks private information about a device and a web service. API Keys also link to permissions that restrict API commands from IP addresses, rate limits, devices, and web services.

Session

An authenticated channel to RealTime.io APIs. A session file gets created on the server to store persistent information about about a user’s session. Your application can read/write to a session. Each session is identified with a sessionID.

Stream

A persistent HTTP conntention to a RealTime.io service that contains every message from a subscribed device and authenticated web services.

Channel

A RealTime.io Channel is a web service that RealTime.io has access to. Channels are typically services such as data logging, email notifications, or access to external services such as NOAA Weather and Twitter. Each channel has a unique channelID that a device can send requests to. RealTime.io will replay the response back to a device from the channel. Channels are identified by a Channel Number between 0 and 65535. For example, the Admin Channel is Channel 65535.

API URLs

RealTime.io API calls use either HTTP or HTTPS and use a consistent URL structure.

http://api.realtime.io/[version]/[resource]

API Keys

All requests to the Gateway API are governed by API keys. They are pre-assigned and give permission for a particular action related to one or many devices. There are two parts of an API key: the key name and the key permissions. The key name is 16 characters long and any printable character can be used. However, every key name must be unique to the RealTime.io server. For the sake of security, the API key name should be randomized. The key permissions are actually lines of text listing the devices channels and operations allowed. Be default all permissions are denied. Only operations specified in the key permissions will be allowed. The actual API key information resides on the RealTime.io cloud server and can be manipulated through the Admin API.

API Resources

API Support

Device Stream

Devices connected to RealTime.io are able to produce a real-time stream of data that includes GPIO pin values and serial data input. The Device Stream API allows web browser and mobile applications to access device streams. As data from devices enters a RealTime.io server, it is redistribusted to a “stream”. Steaming connections are established with an HTTP GET that includes an API Key. The API Key establishes the set of devices for which data will be present. This type of HTTP connection delivers the data asynchronously. As data is being received from devices, RealTime.io will immediately resend the message to an authorized stream. Each piece of data in a stream is wrapped in a JSON object to identify its origin.

Resource URL

http://api.realtime.io/v1/stream?apikey=[apikey]

Method

HTTP GET

Required Parameters

apikey

Authenticated token that represents one device or many devices

Optional Parameters

callback=[callback]

Add a javascript callback function to the streaming response

script=true

Wraps the streaming response in HTML script tags

chunksize=[padding_size]

Adds the number of spaces specified by padding_size to the end of each streaming response. This will help with some browser implementations. By default the padding size is set to 4096 spaces.

encoding=[plain / base64]

Converts all data from device to base64 encoding, otherwise data will be plain. Note that some character sent from a device can break the JSON object.

Response

The initial response to a stream request using a valid API Key, will include the the callback function name or HTML script tags if specified. After that, additional JSON objects will be delivered as data is collected from the device. The data responses will also have callback or script tags if specified.

JSON Object

{
    "serial": "[serial]",
    "channel": "[channel]",
    "status": "[connected / disconnected]",
    "source": "[source]",
    "timestamp": "[timestamp]",
    "ms": "[ms]",
    "encoding": "[encoding]",
    "payload": "[payload]"
}

JSON Keys

  • [serial]  – The serial ID if the device from which the data original data came
  • [channel] – The channel on which the device used to send the data
  • [status]- Connected or Disconnected
  • [source] – ‘remote’ if the data is from a device, ‘server’ if this is an update from the server
  • [timestamp] – Epoch time in seconds of the message’s receipt by the server
  • [ms] – Milliseconds after the timestamp that defines the exact subsecond of message’s receipt
  • [encoding] – ‘plain’ or ‘base64’
  • [payload] – the actual data

cURL Example

curl http://api.realtime.io/v1/stream?apikey=[apikey]

 

Sending Data to a Device

Data can be sent to individual devices by using the send command. The send command requires the use of an API Key that has write permission. Sending data uses the HTTP POST method with the API Key in the header or as a parameter.

API Command: gateway/send

Resource URL

http://api.realtime.io/v1/gateway/send

Optional Parameters

callback=[callback]

Add a javascript callback function to the response (JSONP)

Method

HTTP POST

Header

X-APIKEY: [apikey]

Content Type

application/json

Body

{
    "serial":"[serial]",
    "channel":"[channel]",
    "encoding":"[encoding]",
    "payload":"[payload]"
}
  • [serial] – Serial Number of the target device
  • [channel] – Channel to which the data will be sent
  • [encoding] – Set to ‘plain’ for messages that do not contain any special characters or ‘base64’ for data that may contain special or non-displayable characters
  • [payload] – Data to be sent to the device

cURL Example

curl -H "X-APIKEY: [apikey]" -H "Content-Type: application/json" -X POST -d '{"serial":"[serial]","channel":"[channel]","encoding":"[encoding]","payload":"[payload]"}' http://api.realtime.io/v1/gateway/send

 

Requesting the IP Address of a Device

If a device is connected to the RealTime.io cloud platform, its remote IP address can be retrieved by sending a request. An API Key with read permission and a Serial Number is required to request the IP Address.

API Command: gateway/request/ip

Resource URL

http://api.realtime.io/v1/gateway/request/ip?apikey=[apikey]&serial=[serial]

Method

HTTP GET

Required Parameters

apikey

Authenticated token that represents one device or many devices with at least read permission

serial

Serial Number of the target device

Optional Parameters

callback=[callback]

Add a javascript callback function to the response (JSONP)

cURL Example

curl http://api.realtime.io/v1/gateway/request/ip?apikey=[apikey]&serial=[serial]

 

Requesting the Connection State of a Device

Applications can use this API command to detect the connection state of a device. A device is either connected or disconnected to a RealTime.io server. An API Key with read permission and a Serial Number is required to request the connection state.

API Command: gateway/request/state

Resource URL

http://api.realtime.io/v1/gateway/request/state?apikey=[apikey]&serial=[serial]

Method

HTTP GET

Required Parameters

apikey

Authenticated token that represents one device or many devices with at least read permission

serial

Serial Number of the target device

Optional Parameters

callback=[callback]

Add a javascript callback function to the response (JSONP)

cURL Example

curl http://api.realtime.io/v1/gateway/request/state?apikey=[apikey]&serial=[serial]

 

Reading GPIO Registers

Iota-enabled devices have GPIO pins that have a mode, state, and value. Using this API command will read the value of a GPIO register or values of all of the GPIO registers.

API Command: gateway/request/register/read

Resource URL

http://api.realtime.io/v1/gateway/request/register/read

Optional Parameters

callback=[callback]

Add a javascript callback function to the response (JSONP)

Method

HTTP POST

Header

X-APIKEY: [apikey]

Content Type

application/json

Body

{
    "serial":"[serial]",
    "channel":"[channel]",
    "register":"[register]"
}
  • [serial] – Serial Number of the target device
  • [channel] – Channel to send request
  • [register] – The name of the register to read

cURL Example

curl -H "X-APIKEY: [apikey]" -H "Content-Type: application/json" -X POST -d '{"serial":"[serial]","channel":"[channel]","register":"[register]"}' http://api.realtime.io/v1/gateway/request/register/read

 

Writing to GPIO Registers

Iota-enabled devices have GPIO pins that have a mode, state, and value. Using this API command will allow applications to write to a GPIO register or write to all of the GPIO registers at once.

API Command: gateway/request/register/write

Resource URL

http://api.realtime.io/v1/gateway/request/register/write

Optional Parameters

callback=[callback]

Add a javascript callback function to the response (JSONP)

Method

HTTP POST

Header

X-APIKEY: [apikey]

Content Type

application/json

Body

{
    "serial":"[serial]",
    "channel":"[channel]",
    "register":"[register]",
    "content":"[content]"
}
  • [serial] – Serial Number of the target device
  • [channel] – Channel to send request
  • [register] – The name of the register to write to
  • [content] – The contents to write to a register

cURL Example

curl -H "X-APIKEY: [apikey]" -H "Content-Type: application/json" -X POST -d '{"serial":"[serial]","channel":"[channel]","register":"[register]","content":"[content]"}' http://api.realtime.io/v1/gateway/request/register/write