Api Home

Joanna Rozestwinska edited this page Apr 9, 2015 · 3 revisions

This API represents an external service for interacting with the enableiot.com system

API Authorization

####Authorization Tokens

Nearly all of the REST methods require an authorization token. There are two types of authorization tokens:

  1. Device token - this token is assigned to a device (client) when it activates the device. The token has very limited permissions such as enabling the device to create time series and to send observations for those time series. Note: this token is only provided when a device is activated. The user should save the token for later use.

  2. User token - this token is derived using a user's credentials. The token enables access to the user resource, the account resources associated with the user, device resources associates with those account resources, etc.

Note: User tokens are very powerful. Treat user tokens just as you would treat a password.

####Authorization Header For REST methods which require an authorization token, the token must be sent using the HTTP 'Authorization' header, like this:

Authorization: Bearer<space><token>

For example:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9....

API Root

API entry point.

/v1/api

Note, while the individual messages are versioned, the entire API version will need to change when message changes result endpoint incompatibility.

Data Structure

 +---------+             +------+                  
 | Account |<----------->| User |                  
 +----+----+             +------+                  
      |                                            
      v                                            
 +----+---+                                        
 | Device |                                        
 +----+---+                                        
      |                                            
      v                                            
+-----+-----+                                      
| Component |                                      
+-----+-----+                                      
      |                                            
      |      +----------+                          
      -------+ Actuator |                          
      |      +----------+                          
      |                                            
      |      +--------------+       +-------------+
      -------+ Time Series  +------>+ Observation |
             +--------------+       +-------------+
Object Definition
Account A logical organization that groups multiple devices, and allows one or more users with common interests to manage these devices.
User A human who interacts with the system though the UI. Users can have different roles. Note that multiple users can manage an account and a user can manage or view multiple accounts
Time Series (sensor) Represents a series of values obtained from a specific sensor. Examples: temperature, humidity, wind speed, geographic coordinates, sound waveforms, images. A single device can produce many time series.
Actuator Represents a setting which can be modified on a device, typically resulting in physical response. Examples: turn on a LED, capture an image. The actuator can change the setting and/or output its current state.
Component A super class of both a Time Series and an Actuator.
Device A endpoint containing one or more components. The components can be an integral part of the device or external objects that use the device as a hub. A device does not necessarily have a route to the cloud. Each Device has a globally unique identifier deviceId.

API Services

CRUD or create, read, update and delete, represents a set of basic functionality on an model identity.

Account ID

Many of our API resource paths contain the accountId as part of it. So it's important for API consumers to retrieve this information. At the moment there are two possible ways to do that:

Common Errors

After working with many developers, these are some of the more common errors we see:

HTTP Response Message Meaning
400 {"code":400,"message":"Invalid request"} Malformed JSON
401 Unauthorized call over http: rather than https: -or- Authorization misspelled -or- Bearer misspelled -or- expired token -or- invalid token
409 Conflict User/device/component already exists
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.