HTTP API Overview

This is a lightweight HTTP-based API for writing to and reading from the Exosite One Platform. It is intended for bandwidth-constrained applications. It provides the ability to write new data points or read the latest data point.

If you're completely new to Exosite's APIs, you may want to read the API overview first.

Procedures

Timeseries Data Procedures

Write - write new data to a set of dataports

Read - read the latest data from a set of dataports

Hybrid Write/Read - write a set of dataports, then read a set of dataports

Long-Polling - be notified immediately when a dataport is updated

Record - write data to historical timestamps

Provisioning Procedures

Activate - activate device and get device's CIK

List Available Content - get a list of content available to device

Get Content Info - get meta information about content file

Download Content - get content file

Utility Procedures

Timestamp - get the current unix timestamp

Libraries and Sample Code

Sample code is available that uses this API.

Notational Conventions

This document uses a few notational conventions:

HTTP Responses

Typical HTTP response codes include:

Code Response Description
200 OK Successful request, returning requested values
204 No Content Successful request, nothing will be returned
4xx Client Error There was an error* with the request by the client
401 Unauthorized No or invalid CIK
5xx Server Error There way an error with the request on the server

* Note: aliases that are not found are not considered errors in the request. See the documentation for read, and write and Hybrid write/read for details.

Data Procedures

Write

Write one or more dataports of alias <alias> with given <value>. The client (e.g. device, portal) is identified by <CIK>. Data is written with the server timestamp as of the time the data was received by the server. Data cannot be written faster than a rate of once per second, doing so results in undefined behavior. If multiple aliases are specified, they are written at the same timestamp.

request

POST /onep:v1/stack/alias HTTP/1.1 
Host: m2.exosite.com 
X-Exosite-CIK: <CIK> 
Content-Type: application/x-www-form-urlencoded; charset=utf-8 
Content-Length: <length> 
<blank line>
<alias 1>=<value 1>&<alias 2...>=<value 2...>&<alias n>=<value n>

response

HTTP/1.1 204 No Content 
Date: <date> 
Server: <server> 
Connection: Close 
Content-Length: 0 
<blank line>

example

$ curl http://m2.exosite.com/onep:v1/stack/alias \
    -H 'X-Exosite-CIK: <CIK>' \
    -H 'Accept: application/x-www-form-urlencoded; charset=utf-8' \
    -d '<alias>=<value>'

Read

Read the most recent value from one or more dataports with alias <alias>. The client (e.g. device or portal) to read from is identified by <CIK>. If at least one <alias> is found and has data, data will be returned.

request

GET /onep:v1/stack/alias?<alias 1>&<alias 2...>&<alias n> HTTP/1.1
Host: m2.exosite.com
X-Exosite-CIK: <CIK>
Accept: application/x-www-form-urlencoded; charset=utf-8
<blank line>

response

HTTP/1.1 200 OK
Date: <date>
Server: <server>
Connection: Close
Content-Length: <length>
<blank line>
<alias 1>=<value 1>&<alias 2...>=<value 2...>&<alias n>=<value n>

example

$ curl http://m2.exosite.com/onep:v1/stack/alias?<dataport-alias> \
    -H 'X-Exosite-CIK: <CIK>' \
    -H 'Accept: application/x-www-form-urlencoded; charset=utf-8'

Hybrid write/read

Write one or more dataports of alias <alias w> with given <value> and then read the most recent value from one or more dataports with alias <alias r>. The client (e.g. device, portal) to write to and read from is identified by <CIK>. All writes occur before all reads.

request

POST /onep:v1/stack/alias?<alias r1>&<alias r2...>&<alias rn> HTTP/1.1
Host: m2.exosite.com
X-Exosite-CIK: <CIK>
Accept: application/x-www-form-urlencoded; charset=utf-8
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: <length>
<blank line>
<alias w1>=<value 1>&<alias w2...>=<value 2...>&<alias wn>=<value n>

response

HTTP/1.1 200 OK
Date: <date>
Server: <server>
Connection: Close
Content-Length: <length>
<blank line>
<alias r1>=<value 1>&<alias r2...>=<value 2...>&<alias rn>=<value n>

example

$ curl http://m2.exosite.com/onep:v1/stack/alias?<alias_to_read> \
    -H 'X-Exosite-CIK: <CIK>' \
    -H 'Accept: application/x-www-form-urlencoded; charset=utf-8' \
    -d '<alias_to_write>=<value>'

Long Polling

The read procedure now supports long polling. Long polling is a method of getting a server push without the complexities of setting up publicly accessible HTTP server endpoints on your device. As the name suggests, long polling is similar to normal polling of an HTTP resource, but instead of requiring the client to make a new request to the server constantly, the server will wait to return until it has new information to return to the client (or a timeout has been reached).

To perform a request with long polling simply add the header Request-Timeout: <miliseconds> to your request. The server will then wait until a new datapoint is written to the given dataport and will then immediately return the value. If no datapoint is written before that time a 304 Not Modified is returned and the client may make another long poling request to continue monitoring that dataport.

You may also optionally add an If-Modified-Since header to specify a start time to wait. This is exactly the same as the alias.last semantics in scripting. You will want to use this if it's important that you receive all updates to a given dataport, otherwise it is possible to miss points that get written between long polling requests.

Note: Only one dataport may be read at a time when using long polling.

request

GET /onep:v1/stack/alias?<alias 1> HTTP/1.1
Host: m2.exosite.com
X-Exosite-CIK: <CIK>
Accept: application/x-www-form-urlencoded; charset=utf-8
Request-Timeout: <timeout>
If-Modified-Since: <timestamp>
<blank line>

response

When the dataport is updated:

HTTP/1.1 200 OK
Date: <date>
Server: <server>
Connection: Close
Content-Length: <length>
Last-Modified: <datapoint-modification-date>
<blank line>
<alias>=<value>

If the dataport is not updated before timeout:

HTTP/1.1 304 Not Modified
Date: <date>
Server: <server>
Connection: Close
Content-Length: <length>
<blank line>

When the dataport is updated and a value is returned, a Last-Modified header is included. When it is vital for your application to receive all updates to a dataport, you can pass the Last-Modified header value back to the If-Not-Modified-Since header in your next request to make sure that you don't miss any points that may have been written since the last request returned.

example

$ curl http://m2.exosite.com/onep:v1/stack/alias?<dataport-alias> \
    -H 'X-Exosite-CIK: <CIK>' \
    -H 'Accept: application/x-www-form-urlencoded; charset=utf-8'
    -H 'Request-Timeout: 30000'
    -H 'If-Modified-Since: 1408088308'

record

Write data to one or more historical timestamps of one or more aliases. The client (e.g. device, portal) is identified by <CIK>. Timestamps to the same alias cannot have less than 1 second differences between each other, doing so results in error in response.

request

This example records to <alias 1> in <timestamp 1> and <timestamp 2>, while records to <alias 2> in <timestamp 3> and <timestamp 4>.

POST /onep:v1/stack/record HTTP/1.1
Host: m2.exosite.com
X-Exosite-CIK: <CIK>
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: <length>
<blank line>
alias=<alias 1>&<timestamp 1>=<value 1>&<timestamp 2>=<value 2>&alias=<alias 2>&<timestamp 3>=<value 3>&<timestamp 4>=<value 4>

response

HTTP/1.1 204 No Content 
Date: <date> 
Server: <server> 
Connection: Close 
Content-Length: 0 
<blank line>
HTTP/1.1 409 Conflict
Date: <date>
Server: <server>
Connection: Close
Content-Length: <length>
<alias 1>=<timestamp 1>&<alias 2>=<timestamp 3>

example

$ curl https://m2.exosite.com/onep:v1/stack/alias/<alias> \
    -H 'X-Exosite-CIK: <CIK>' \
    -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
    -d '<timestamp 1>=<value 1>&<timestamp 2>=<value 2>'

Provisioning Procedures

Activate

Activates and returns <cik> of client administrated by Vendor <vendor>, identified my the model ID <model> associated with Serial Number <sn>. Client must be enabled via /provision/manage/model/<model>/<sn>, the enabled state must not have expired, and the client must not have already been activated.

POST /provision/activate HTTP/1.1
Host: m2.exosite.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: <length>

vendor=<vendor>&model=<model>&sn=<sn>

response

HTTP/1.1 200 OK
Date: <date>
Server: <server>
Connection: Keep-Alive
Content-Length: <length>
Content-Type: text/plain; charset=utf-8

<cik>

Response may also be:

example

This command activates a device with serial number 12345678 and returns its CIK.

$ curl http://m2.exosite.com/provision/activate \
    -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
    -d "vendor=mysubdomain&model=myclientmodel&sn=12345678"

List Available Content

List content <id>s. Caller with <DeviceCIK> must have an activated serial number in given <vendor> <model> name space.

GET /provision/download?vendor=<vendor>&model=<model> HTTP/1.1
Host: m2.exosite.com
X-Exosite-CIK: <CIK>
Content-Length: <length>
<blank line>

response

HTTP/1.1 200 OK
Date: <date>
Server: <server>
Connection: Keep-Alive
Content-Length: <length>
Content-Type: text/csv; charset=utf-8

<id 1>
<id 2...>
<id n>

Response may also be:

Download Content

If caller with <CIK> has an activated SN in given <vendor> <model> name space, and is authorized for the content, then the <id> content blob, or its requested range, is returned. The header Range: bytes=<range-specifier>, if specified, allows the caller to request a chunk of bytes at a time. <range-specifier> takes the form of X-Y where both X and Y are optional but at least one of them must be present. X is the start byte position to return, Y is the end position. Both are 0 based. If X is omitted, Y will request the last Y count of bytes of the content. If Y is omitted, it will default to the end of the content. Note that Content-Type of <blob> is based on the type set in the POST to /provision/manage/content/<model>/<id>.

GET /provision/download?vendor=<vendor>&model=<model>&id=<id> HTTP/1.1
Host: m2.exosite.com
X-Exosite-CIK: <CIK>
{Range: bytes=<range-specifier>}
<blank line>

response

HTTP/1.1 200 OK
Date: <date>
Server: <server>
Connection: Keep-Alive
{Accept-Ranges: bytes}
Content-Length: <number of bytes being returned>
{Content-Range: bytes <first position>-<last position>/<total length>}
Content-Type: <content-type>

<blob>

Response may also be:

Get Content Info

If caller with <CIK> has an activated SN in given <vendor> <model> name space, and is authorized for the content, then the <id> content information is returned.

GET /provision/download?vendor=<vendor>&model=<model>&id=<id>&info=true HTTP/1.1
Host: m2.exosite.com
X-Exosite-CIK: <CIK>
Content-Length: <length>
<blank line>

response

HTTP/1.1 200 OK
Date: <date>
Server: <server>
Connection: Keep-Alive
Content-Length: <length>
Content-Type: text/csv; charset=utf-8

<content-type>,<byte-size>,<updated-timestamp>,<meta>

Response may also be:

Utility Procedures

Timestamp

Get the current time according to the server.

request

GET /timestamp HTTP/1.1
Host: m2.exosite.com
<blank line>

response

HTTP/1.1 200 OK
Date: <date>
Server: <server>
Connection: Keep-Alive
Content-Length: <length>
Content-Type: text/plain; charset=utf-8

<timestamp>