The Electric Imp impCentral API provides developers with a means to access all of the functionality provided by Electric Imp’s web-based development environment, allowing them to develop Electric Imp applications and manage devices using the tools of their choice. The following examples demonstrate common actions that you might perform using the impCentral API.
Please see the accompanying impCentral API Reference for a full list of endpoints and resource/object identifiers, and How to Use the impCentral API for general API usage guidance. The impCentral API Primer describes the resources that you access using the API.
The code that follows uses JavaScript/Node.js. For a working example using Squirrel, please see impMonitor in the Electric Imp GitHub examples repository. This provides a web-based status readout of your development devices and is based upon the impCentral API.
The following example is written in Node.js and demonstrates how you can access your Products and their Device Groups. It comprises a series of nested HTTPS request made to the API, first to obtain the access token required to authorize all further requests for data. Requesting an access token involves submitting your account’s username or registered email address, and your password. When an access token has been retrieved, further calls are made to obtain a list of the account’s Products. For each Product, the code retrieves lists of the Device Groups, if any, assigned to that Product.
For convenience, the key data for each object are stored in an internal data structure: an array products holds Product objects, each of which stores the Product’s name, ID and an array of Device Group objects. The Device Group objects just include the object’s ID and name. Ten seconds after the list of Products has been received, all the data received is displayed in the console. This should be sufficient time to retrieve all of each Product’s component Device Groups.
The following example is written in Node.js and demonstrates how you can upload code to a known Device Group. Code is assigned to a Device Group by creating and POST-ing a Deployment object containing the new or updated code to the API endpoint /deployments. The object also contains an identifier to indicate which Device Group it should be deployed to.
In the code below, the uploaded code is read in from local files in the same directory as the script (the file data objects are first converted to strings) and inserted into the Deployment’s attributes object. The known Device Group ID comes from the details array (see the example above). Note that the code assumes details is populated with at least one Product which has at least one Device Group assigned to it.
The code uses the API access token, which is assumed to be have been retrieved already as per the example above. The Working with Access Tokens example shows you might retain and refresh access tokens.
The following example is written in Node.js and demonstrates how you can get a list of your unassigned devices. It sends a GET request to the API endpoint /devices, which returns a list of all the account’s devices. We are only interested in unassigned devices, ie. devices which have no devicegroup entry in their list of relationships, and any we find are added to a local array, devices. Once the devices have been parsed, we print the list out.
The code uses the API access token, which is assumed to be have been retrieved already as per the Login example, above. The Working with Access Tokens example shows you might retain and refresh access tokens.
The following example is written in Node.js and demonstrates API data pagination. It sends a GET request to the API endpoint /deployments, which returns a list of all of the account’s deployments. When the first page of data is returned, we store a simple version of each deployment record in the array deployments. We then check whether the returned data’s links field contains a next object — if it does this gives us a pointer to the next page of data, which we parse and apply by re-calling getDeployments(). A message indication which page we are getting next is printed.
This process repeats until links does not contain next, in which case we simply print out the number of deployments in the account. Of course, this may be fewer deployments than the default page size, which is 20 items.
The code uses the API access token, which is assumed to be have been retrieved already as per the Login example, above. The Working with Access Tokens example shows you might retain and refresh access tokens.
The following example is written in Node.js and demonstrates the use of Access Tokens and local storage. When first run, the code has no access token, so it checks for a local file (.impCentralData, stored in the same directory as the script) to see it it has a stored access token. In the file doesn't exist it’s created; whether it’s newly created or simply empty, the code gets a new access token and saves it to the file before proceeding to access the impCentral API’s product listing functionality.
If the file does contain an access token, the code checks the token has not expired. If that’s the case, the code uses the saved refresh token to acquire a new access token; otherwise it proceeds with the existing access token.
The following example is written in Node.js and demonstrates how you can initialize a log stream, open that stream for logging and add a device to the stream. Logging is detailed in How to Use the impCentral API — essentially, it uses the server-sent events (SSE) protocol to issue formatted chunks of data on a maintained connection (the open stream). The code stores bytes arriving this way until it detects SSE’s end-of-item marker: two newline characters (/n/n). At this point the stored data is processed and any further incoming data is stored. Processing involves separating out the message fields (event and data), and interpreting and displaying them as appropriate.
The code uses the API access token, which is assumed to be have been retrieved already as per the Login example, above. The Working with Access Tokens example shows you might retain and refresh access tokens.