Developer API
Easily integrate applications and access data
The M2M Intelligence Infrastructure has a comprehensive set of APIs to enable integration, data access and management. The following is an overview of the API architecture and the types of actions that can be performed using its APIs.
M2Mi Digital Infrastructure Architecture Overview
The modular and composable nature of the APIs makes it scalable as well as flexible. The following image describes at a high level the architecture of the M2M Intelligence:
API Overview
Users interact with the M2M Intelligence application through a secure REST API. Every interaction with the application must be done through the API and use a secure HTTPS communication channel. The application's API architecture divides in 7 main components:
- Identity Management to manage and authenticate users
- Object Store to manage and store the objects of the model
- Data Store to manage and store the data collected from devices
- Connectivity Management to manage the cellular connectivity of devices
- Device Management to send commands to devices
- Node to interact with devices and collect their data
- Lockbox to control resource access based on policies
Each component gives access to a subset of M2M Intelligence resources through a set of REST web services whose input and output are expressed in JSON. The methods accepted by M2M Intelligence are POST, PUT, GET, and DELETE.
URL template
Each component of the M2M Intelligence application has its own set of independent and user-friendly URL whose general format is of the form
https://<base url>/iotplatform/v1/rs/<component>/<resource>
where <component> and <resource> are the name of the target application's component and resource respectively. The 7 components of the application map to the following API
| Component | API |
| Identity Management | /auth |
| Object Store | /objectStore |
| Data Store | /dataStore |
| Connectivity Management | /connectivity |
| Device Management | /manager |
| Node | /node |
| Lockbox | /lockbox |
For example, to create a new device in the Object Store one would use the POST method and target the component “objectStore” with the resource “device”.
Authentication
Only valid users can interact with the M2M Intelligence application. Every call to the API is authenticated via HTTP Basic Authentication and must include the HTTP Authorization header
Authorization: Basic <Base64 encoded credentials>
Authorization
All requests issued to the M2M Intelligence application are subject to authorization based on the requester’s identity and role. When a user operation requires one component to interact with another one in the name of the user, the credentials of the calling user are propagated to ensure that authentication and authorization are propagated across the entire operation.
Error Code
In case of error the M2M Intelligence application returns standard HTTP response codes as described in RFC2616. The following codes may be returned by the platform:
| Code | Name | Description |
| 200 | Success | The request succeeded. |
| 201 | Created | The request succeeded and resulted in a new resource being created. |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax. |
| 401 | Unauthorized | Authentication has failed. Credentials were not valid or not provided. |
| 403 | Forbidden | Authorization has failed. The requestor’s role was not sufficient to access the target resource. |
| 404 | Not Found | The request failed because the target resource was not found. |
| 405 | Method not Allowed | The employed HTTP method cannot be used on the target resource. |
| 409 | Conflict | The request failed due to a conflict with the target resource (duplicate, in use, etc). |
| 500 | Internal Server Error | The request failed due to a software error in the application. |
| 501 | Not Implemented | The employed method is not yet implemented for the target resource. |
Outcome
In addition to the HTTP codes listed above, the API typically returns a JSON object containing additional information about the processing of the request and/or the target resource. In its simplest form, this object indicates if the request was a success, the associated HTTP code, and some details in case of an error:
{
"success": false,
"code": 404,
"detail: "Device [54c6897fed506edb1abeeeab] unknown."
}
In some situations the API may return one or more entries as the result of a GET or POST method, in which case the outcome will indicate the number of entries returned:
{
"success": true,
"code": 200,
"count": 1,
"entry": [{…} ]
}
Pagination
When multiple entries are returned as the result of a GET on a collection of resources, the outcome is paginated and only a subset of the target collection is returned. In this case the outcome contains information about the current page, the size of the collection, as well as link to the next and previous pages:
{
"success": true,
"code": 200,
"count": 20,
"entry": [{…}, … ,{…}]
"page: {
"current": 3,
"size": 20,
"total": 7,
"count": 132,
“next": "/objectStore/device?pageSize=20&page=4&before=550c39ec0cf2be59799aa0db",
“prev": "/objectStore/device?pageSize=20&page=2&after= 55128f3b0cf28e19febc2feb"
}
For more information about the M2M Intelligence API architecture and how you can integrate into the platform, please contact us.