data

Exosite Data API

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.

Table of Contents

Libraries and Sample Code

Notational Convention

HTTP Responses

####Procedures

Write - write new data to a set of dataports

Read - read the latest data from a set of dataports

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

IP - get the IP address of the host server

Libraries and Sample Code

Sample code is available that uses this API.

• Python hello world
• Arduino POST
• Arduino-compatible devices (Using Arduino Library) - for, e.g., 8-bit micros running C/C++ code
• Python read and write example with socket, Python - Get IP Address Example - socket level code intended as a reference for implementation in other languages
• Python read and write example with httplib

Notational Conventions

This document uses a few notational conventions:

• JSON is pretty printed for clarity. The extra whitespace is not included in the RPC JSON.
• Comments (//) are occasionally included in JSON to give hints or provide detail. These comments are not included in actual requests or responses.
• A name in angle brackets, e.g. <myvar>, is a placeholder that will be defined elsewhere.
• number indicates a number, e.g. 42
• string represents a string, e.g. "MySensor"
• | represents multiple choice
• = represents default value
• ... represents one or more of the previous item

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
5xx	Server Error	There way an error with the request on the server

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 with this API.

#####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>

• See HTTP Responses for a full list of responses.

###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>

• Response may also be HTTP/1.1 204 No Content if either none of the aliases are found or they are all empty of data
• See HTTP Responses for a full list of responses

###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 204 No Content 
Date: <date> 
Server: <server> 
Connection: Close 
Content-Length: <length> 
<blank line>
<alias r1>=<value 1>&<alias r2...>=<value 2...>&<alias rn>=<value n>

• Response may also be HTTP/1.1 204 No Content if either none of the aliases are found or they are all empty of data
• See HTTP Responses for a full list of responses.

###IP

Return the IP address of the host server.

#####request

GET /ip HTTP/1.1 
<blank line>

#####response

HTTP/1.1 200 OK 
Date: <date> 
Server: <server>
Connection: Close
Content-Type: text/plain; charset=utf-8
Content-Length: 19
<blank line>
173,255,209,28,0,80