Web Services Series Part 1: Working with REST APIs

April 30, 2018 | Lizzie Prader, Software Engineer

The Moddable SDK includes modules that implement a variety of networking protocols, giving developers the flexibility to build applications that interact with all sorts of other devices and cloud services. A common way to communicate with cloud services is through RESTful APIs, which are based on HTTP.

You can find several basic example apps that communicate with web services in the http and services folders of our open source repository, including the streaming-adafruit-io example app which sends data to the Adafruit IO streaming service. This document explains how this app was written based on the Adafruit IO REST API documentation, together with general information about implementing REST APIs using the Moddable SDK.

Note: This document assumes you have a basic familiarity with the Moddable SDK's HTTP Request class. You can find the documentation in the class HTTP Request section of the network documentation.

Setup

When you're finished, open the manifest of the example app and replace the value of the username parameter of the config object with your username.

{
    ...
    "config": {
        "username": "YOUR_USERNAME_HERE",
    ...
}

• Click Feeds in the sidebar
• Select Create a new Feed from the Actions menu
• Give your feed a name and click the Create button

Replace the value of the feedKey parameter of the config object with the name of your feed.

{
    ...
    "config": {
        ...
        "feedKey": "YOUR_FEED_KEY_HERE",
    ...
}

Creating a Request

host

let request = new Request({
    host: "io.adafruit.com",
    ...
});

path

The path parameter must match this format, so the host is removed from the sample URL and the variables (denoted by curly braces) are replaced with the username and feedKeyparameters specified in the manifest.

let request = new Request({
    ...
    path: `/api/v2/${config.username}/feeds/${config.feedKey}/data`,
    ...
});

method

let request = new Request({
    ...
    method: "POST",
    ...
});

headers

let request = new Request({
    ...
    headers: [ "X-AIO-Key", config.AIOKey, "Content-Type", "application/json" ],
    ...
});

All you have to do in the example app is replace the value of the AIOKey parameter of the config object with your AIO key.

{
    ...
    "config": {
        ...
        "AIOKey": "YOUR_AIO_KEY_HERE",
    ...
}

let request = new Request({
    ...
    path: `/api/v2/${config.username}/feeds/${config.feedKey}/data?X-AIO-Key=${config.AIOKey}`,
    headers: [ "Content-Type", "application/json" ],
    ...
});

Content-Type

There are many possible values for this header. The responses to this Stack Overflow thread provide a good summary of its structure and some of the common values.

In this example we specify the type application/json because the body of the request is in JSON format.

body

The example app only includes the required value field. The body parameter has to be a String or an ArrayBuffer, so the JSON object is converted into a string:

let request = new Request({
    ...
    body: JSON.stringify({ value: data }),
    ...
});

Response

To trace everything that an HTTP server sends back to the console, you can use the following:

request.callback = function(message, value, etc) {
    if (value) trace(`value: ${JSON.stringify(value)}`);
    if (etc) trace(`, etc: ${JSON.stringify(etc)}\n`);
    else trace("\n");
}

request.callback = function(message, value, etc) {
    if ((message == 2) && (value == "status")) {
       if (etc == "200 OK") {
           trace(`Sent data "${data}"\n`);
        } else {
           trace(`Error sending data "${data}". Error code: ${etc}\n`);
        }
     }
}

Conclusion

Translating REST APIs into HTTP requests is a simple and straightforward process, but it is a skill worth learning. A basic understanding of how to use REST APIs enables developers to write applications that communicate with a huge variety of web services and create more compelling connected products.