Overview

Skill Level: Any Skill Level

This recipe shows how to use the IBM Watson IoT Platform REST API to perform useful functions such as bulk registering devices.

Ingredients

Access to Bluemix‚ĄĘ and an instance of the IBM Watson IoT Platform.

A REST client - this recipe uses the RESTClient addon for Firefox however you may use any REST client.

 

Note that since this Recipe was created, IBM Watson IoT Platform has updated it's default security for incoming connections, making them to be via TLS. Thus ensuring that only secure connections shall be allowed to the platform from the incoming requests from any Devices/Gateways and Applications.

Before using this recipe, review the documentation mentioned in the Watson IoT Platform Blog

Step-by-step

  1. Introduction

    When you want to connect your device(s) to the IBM Watson IoT Platform you need to create Device Types and Devices. Usually this is performed using the platform user interface and whilst this is not a difficult task – if you are registering many devices (such as setting up a workshop for example) it can be time consuming.

    The IoT Platform has a REST API that can be used to perform many device-related tasks such as device diagnostics and adding/removing devices in bulk.  

    In this recipe you will see how to use a simple browser-based REST client to connect to the REST API and bulk-add devices to the platform.

    It is assumed you have already deployed an instance of the IBM Watson IoT Platform. It is also assumed that you already have a Device Type defined (note that the REST API may also be used to create Device Types)

    What you will need:

    1. The org id of your IoT Platform
    2. An API key (Step 2 below)
    3. A REST Client (Step 3 below)
  2. Generate an API Key

    Start in your IoT Platform Dashboard.

    In the sidebar, click Apps:

    IBM_Watson_IoT_Platform-Apps

    Click Generate API Key:

    GenerateAPIKey

    Copy the generated API Key and Authentication Token. You will need these in the next step so paste them into a temporary text file (there is no way to recover the Authentication Token once you have closed this window)

    KeyDetails

    Leave the API Role as Standard Application (if you want to know more about roles see here: https://new-console.ng.bluemix.net/docs/services/IoT/roles_index.html)

    (Optional) Add a comment so you know for what purpose the API key is being used

    (Optional) Set a date for the API key to automatically expire

    Comment

    Once you are sure you have recorded the API Key and Authentication token – click Generate:

    Generate

  3. Setup a REST Client

    The following steps should be performed in the REST Client. You can use any REST client that you like – these instructions are for the RestClient addon for Firefox. You can download the RestClient addon by clicking this link.

    Add Authentication:

    In the menu bar, click Authentication > Basic Authentication:

    Auth1

    In the Username field, enter the API Key you recorded earlier

    In the Password field, enter the Authentication Token you recorded earlier

    Click Okay

    Auth2

    Add a Custom Header:

    In the menu bar, click Headers > Custom Header:

    CustomHeaders

    In the Name field, type Content-Type

    In the Value field, type application/json

    Click Okay:

    Header

  4. Define Devices in JSON

    Devices are defined using JSON-formatted text which is then POSTed to the REST API. Copy the following into a text editor and modify it to reflect your device(s) details. Note that this sample registers two devices but could be easily modified to register as many as you need:

    [
    {
    "typeId": "SensorTag",
    "deviceId": "SensorTag3",
    "deviceInfo": {
    "serialNumber": "10001",
    "manufacturer": "TI"
    },
    "metadata": {},
    "authToken": "12345678"
    },
    {
    "typeId": "SensorTag",
    "deviceId": "SensorTag4",
    "deviceInfo": {
    "serialNumber": "10002",
    "manufacturer": "TI"
    },
    "metadata": {},
    "authToken": "12345678"
    }
    ]

    You can also add other metdata to the devices such as location – check the documentation in the link provided at the end of this recipe.

  5. Create Devices in the IoT Platform

    The base URI for the IBM Watson IoT Platform REST API is:

    https://orgId.internetofthings.ibmcloud.com/api/v0002/

    Remember to substitute your orgId in the above URI

    The URI to bulk-add devices is:

    https://orgId.internetofthings.ibmcloud.com/api/v0002/bulk/devices/add

    To add devices in bulk – set the REST method to POST, insert the above URI (with your orgId substituted) and paste your device JSON into the body:

    RESTClient_POST

    Click Send

    You should receive a response header with the status code 201 Created – and the response body contains the devices that were added:

    Response

    Response2

    For other response codes as well as full details of other operations that may be performed using the REST API – consult the documentation here:

    https://docs.internetofthings.ibmcloud.com/swagger/v0002.html

     

     

     

Join The Discussion