Api Home

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.

• User Management
• Account Management
• Device Management
• Component Types Catalog - Registry of supported Component Types
  • Component Types List - Full List of supported Component Types
• Rule Management
• Data API - Send/query Data on behalf of a specific account from specific device
• Alert Management
• Error Handling - Error Handling Message Structure and considerations

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:

• Get [an Authorization Token] (https://github.com/enableiot/iotkit-agent/wiki/Authorization-API#rest-api-for-get-a-new-authorization-token-users) and then you have to [get the info related to that token] (https://github.com/enableiot/iotkit-agent/wiki/Authorization-API#rest-api-for-authorization-token-validation). Inside this JSON there is a array which contains all the information of the accounts associated with the given token.
• You can also get the accountId from our Dashboard by going to the Account menu and picking up the Details tab.

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