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:
- The org id of your IoT Platform
- An API key (Step 2 below)
- A REST Client (Step 3 below)
Generate an API Key
Start in your IoT Platform Dashboard.
In the sidebar, click Apps:
Click Generate API Key:
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)
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
Once you are sure you have recorded the API Key and Authentication token – click Generate:
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.
In the menu bar, click Authentication > Basic Authentication:
In the Username field, enter the API Key you recorded earlier
In the Password field, enter the Authentication Token you recorded earlier
Add a Custom Header:
In the menu bar, click Headers > Custom Header:
In the Name field, type
In the Value field, type
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:
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.
Create Devices in the IoT Platform
The base URI for the IBM Watson IoT Platform REST API is:
Remember to substitute your orgId in the above URI
The URI to bulk-add devices is:
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:
You should receive a response header with the status code 201 Created – and the response body contains the devices that were added:
For other response codes as well as full details of other operations that may be performed using the REST API – consult the documentation here: