Skip to main content

The impCentral API Porting Guide

Electric Imp’s ‘New World’ technology is based on a new version of the API which underpins Electric Imp’s online tools, now known as impCentral. The impCentral API unifies the functionality provided by a number of earlier APIs, including the publicly available Build API, into a single, publicly accessible framework that allows third-party tools to communicate with the Electric Imp impCloud™:

Legacy IDE Third-party Tools
API v3 API v4 (Build API)
Electric Imp impCloud

Old World

impCentral Third-party Tools
API v5 (impCentral API)
Electric Imp impCloud

New World

The impCentral API incorporates functionality that was previously unavailable to third-party tools. Specifically, it makes public for the first time endpoints for controlling the Electric Imp Connected Factory Process. These features were not available via the Build API. Please see ‘How To Use The impCentral API’ for more information on Build API deprecation.

This document is aimed at the developers of Build API-based tools, whether they are third-parties or Electric Imp customers, and is intended to help these stakeholders quickly and easily migrate their Build API-based tools to the impCentral API.
 

How The Build And impCentral APIs Differ

The two APIs contain some similarities, but they should in general be assumed to be completely different.

Scope

While the Build API was focused solely on the development process, the impCentral API provides a full set of endpoints to interact with the Electric Imp Platform for production tasks as well as development ones. Although it currently lacks collaboration functionality, this will be added to the impCentral API shortly. Collaboration was not a feature of the Build API.

The impCentral API uses a new conceptual model, so its endpoints work with different resources than those with which the Build API worked. For further information on the impCentral model, please see the impCentral API Primer.

Our guide ‘How To Use The impCentral API’ will show you how to put the new API to use, and the accompanying impCentral API Reference provides a full listing of the new API’s endpoints and resources.

Location

Electric Imp now maintains two Public ImpClouds: one hosted on Microsoft Azure, the other on Amazon Web Services (AWS). The latter is the original impCloud and most accounts and devices are hosted here. The impCentral API is accessed at:

impCloud Domin Version Path
AWS https://api.electricimp.com /v5
Azure https://api.az.electricimp.io /v5

Calls to the API must be made using HTTPS not HTTP.

In the examples that follow, the AWS impCloud is used. For Azure impCloud usage, simply replace the domain — all paths are identical, whatever impCloud you are connecting to.

Authentication

Note Build API keys are not used to authenticate access to the impCentral API.

The impCentral API uses a new authentication scheme. An initial call is made to retrieve an access token which will be used to authorize all subsequent calls to the API for a period of time indicated by the data accompanying the access token. The access token request is itself authenticated using the target account’s master email address or username, and password.

When you first log in and receive an access token, you will also receive a long-lived refresh token which is subsequently used to request new access tokens whenever the one you hold expires. ‘How To Use The impCentral API’ has a full description of this process, plus examples.

Returned Data

The impCentral API returns all requested information in JSON form and in a consistent structure defined by the JSON API specification: the returned JSON contains a data key which holds the requested information. If the target endpoint delivers a list of objects, data will be an array of zero or more data objects of the requested type. If the target endpoint delivers a single object, data will be that object, not an array containing a single object.

Each object within data contains the following keys:

  • id — The system-generated UUID of the object.
  • type — Indicates the impCentral API object type, eg. "product", "devicegroup" or "device".
  • attributes — An object containing object-specific data, eg. "name" or "description".
  • relationships — An object listing the object’s connections to other objects, eg. the Product to which a Device Group belongs.

The relationships property values are themselves objects with id and type properties of their own.

All impCentral data objects contain these four keys, but the keys present in the attributes and relationships objects vary by object type.

Alongside data, there is a further key in the root of the JSON. This is links and it contains data pagination information.

Data Pagination And Filtering

Because Product, Device Group, Device and Deployment lists can be extensive, the impCentral API organizes returned data as a series of pages, each containing 20 data entries by default. This was not the case with the Build API, which returned data en masse. Any JSON returned by the impCentral API contains a key, links, which provides acces to an object containing a set of URLs which allow you to navigate the available pages.

In addition to pagination, the data returned by calls to impCentral API endpoints can be narrowed in scope by applying filters: optional URL-encoded parameters appended to endpoint URLs.

‘How To Use The impCentral API’ has a full description of data pagination and filtering.

Error Handling

The impCentral API uses an entirely new error schema, so you will need to recode how your tools or apps deal with error reporting. For example, the API’s error objects do not include a success key, which has the value false when an error takes place. Each error object in the returned JSON contains different keys than those returned by the Build API.

‘How To Use The impCentral API’ has a full description of the new API’s error reporting system.
 

Build-to-impCentral API Object Mapping

The following sections show how the Build API core objects and their properties map to the impCentral API to help you begin adapting your code. In some cases, there is no direct mapping. You should also be aware that there are additional impCentral API object properties available that are not listed here because they do not have Build API equivalents. You should therefore view the impCentral API Reference for a full description of these additional properties.

impCentral API objects have properties which are themselves objects: attributes and relationships. The properties of these subsidiary objects are listed here by dot syntax, eg. product.attributes.name.

Products, Device Groups and Models

Products are the new way of defining an Electric Imp application and they encompass all of the different programs — development code, production application and factory firmware — that are required to devise a product, to put it into production and to make it successfully perform its role in the field.

Products are new to impCentral, and while they might at first seem to be an upgraded form of the old model concept, this is not entirely the case. Models have more in common with the impCentral API’s Device Group objects — each references code, for example, and devices are assigned to them — than they do with Products. However, Products do share with models the notion of representing a real product in the API. Products essentially allow an application to span multiple models, whereas with the Build API a product was embodied in a single model. You will need to incorporate functionality into your apps or tools to allow your end-users to create, modify and delete Products. Products are accessed via the /products endpoint.

Your code will also need to gain the ability to retrieve the user’s Device Groups (from /devicegroups) and list them, typically hierarchically under the Products to which they belong. Each Device Group’s parent Product is identified using the relationships.product key. You will need to incorporate functionality to allow your end-users to create, modify and delete Device Groups.

Build
Model Key
Equivalent impCentral
Product/Device Group Key
Notes
id id Do not assume that an existing Model ID will be maintained
as the equivalent Product ID,
but their roles are similar
name product.attributes.name
devicegroup.attributes.name
Product names are limited to 1-80 characters.
Device Group names are limited to 1-80 characters
devices N/A Neither Product objects nor Device Group objects include a list
of assigned devices. Instead, these are accessed separately
(see below)

The impCentral API Device Group and Product objects have a number of other keys, which are not part of the Build API. You can find them in the impCentral API Reference.

Devices

Device objects exist in both the Build API and the impCentral API, and provide much the same information about the represented device. However, impCentral API device objects’ structure matches that of other impCentral API objects, in that they have id, type, attributes and relationships keys. Most of the Build API information points are to be found under device.attributes.

Devices and Device Groups are accessed separately, so your code will need to map Devices to Device Groups itself. Each Device’s parent Device Group is identified using the relationships.devicegroup key, and that Device Group’s Product by the relationships.product key. If this key’s value is null, the device is unassigned.

Build
Device Key
Equivalent impCentral
Device Key
Notes
id id The 17-character hex code device ID as returned by
hardware.getdeviceid()
name attributes.name When new devices are added to an account, this value is null.
model_id relationships.product.id See ‘Products, Device Groups and Models’, above
powerstate attributes.device_online Now a boolean value
rssi attributes.rssi Same value as before
agent_id attributes.agent_id Same value as before
agent_status attributes.agent_running Now a boolean value

The impCentral API Device object has a number of other keys, which are not part of the Build API. You can find them in the impCentral API Reference.

Restarting Devices

Individual devices can be restarted by making a POST request to the /devices/{device_ID}/restart endpoint. All of the devices in a given Device Group can be restarted by making a POST request to the /devicegroups/{devicegroup_id}/restart endpoint.

Assigning Devices to a Device Group

When development devices and factory BlinkUp fixtures are added to an Electric Imp account using the Electric Imp mobile app they are initially unassigned. To assign a device to a suitable Device Group, send a POST request to the impCentral API endpoint /devicegroups/{devicegroup_id}/relationships/devices and pass in a Device identifier object (or an array of Device identifiers). This is a simple JSON entity which combines the device’s known ID and its object type (which is always "device"):

{ "type": "device",
  "id": "<device_id>" }

Note that the device ID is the internal device ID, retrieved from an entry in the array returned by the /devices endpoint (see below).

Unassigning Devices

A device can be removed from its Device Group by sending a DELETE request to the /devicegroups/{devicegroup_id}/relationships/devices endpoint and passing in the Device identifier (or an array of Device identifiers), as above. Devices removed this way are unassigned.

Deployments and Code Revisions

The Build API’s code revision object does not exist in the impCentral API, but the latter’s Deployment object provides much the same information and performs a similar role.

Unlike code revision objects, which were accessed through the Build API’s models endpoints, Deployments are not accessed via their parent Product or Device Group objects, but at the separate endpoint, /deployments. Use the relationships.product and relationships.devicegroup keys to determine, respectively, the Product and Device Group to which the Deployment was made.

Every Device Group that has had at least one deployment made to it has a relationships.current_deployment key to provide an easy way to get the group’s Deployment:

{ "relationships: {
  "current_deployment": {
  "type": "deployment",
  "id": "01560db4-1ca2-5af3-de74-fb5cc7c2bf9e" }
 }
}
Build Code
Revision Key
Equivalent impCentral
Deployment Key
Notes
version attributes.sha Deployments have no version. Instead, a unique SHA of the account ID,
agent code and device code used to identify the Deployment version
created_at attributes.created_at These yield identical UTC Unix timestamps
device_code attributes.device_code These yield identical strings
agent_code attributes.agent_code These yield identical strings

 

Logging

Like the Build API, the impCentral API can provide you with both a historical list of log entries for a specific device up to the time of the request, and a stream of log entries as they are posted. Log streaming is implemented very differently under impCentral than it was in the Build API, but historical logs are, like the Build API, made available at the /devices/{device_id}/logs endpoint. However, the structure of the response is different:

Build API

{ "logs" : [
  { "timestamp" : <timestamp>,
    "type" : "Agent",
    "message" : "Agent restarted" },
  ...
  ],
  "poll_url" : "/v4/...",
  "success" : true }

impCentral API

{ "data": [
  { "ts": "2016-02-19T21:05:13.993Z",
    "log_type": "development",
    "type": "device.log",
    "msg": "Hello World!" },
  ...
  ]
}

For full details of how to retrieve historical and current logs via the impCentral API, please see ‘How To Use The impCentral API’.
 

Production Functionality

The Build API only provided access to development devices and processes. The impCentral API includes production devices and processes. For the most part, this simply means that the endpoints listed above return production objects as well as development objects. For example, Production and Factory Device Groups are returned alongside Development Device Groups.

In addition, the production-centric attributes and relationships of these objects can be modified via the API as required and are not hidden. For example, the Build API did not expose a model’s ‘factory firmware’ flag, or allow it to be set or unset. In contrast, the impCentral API does let you assign a Deployment to a Factory Device Group, and you can set the group’s production_target value, for instance:

{ "relationships: {
    "production_target": {
      "type": "development_devicegroup",
      "id": "01560db4-1ca2-5af3-de74-fb5cc7c2bf9e" }
  }
}

The impCentral API also exposes other production functionality that is not part of the objects described earlier in this document. Please see ‘How To Use The impCentral API’ for more information.