Using the Cloud REST API

This guide will cover how to get started with the Managed IoT Cloud (MIC) and use our Cloud REST API to authenticate and access resources. The Cloud REST API can be used to create applications integrated to the MIC.

Note: To use the Cloud REST API, you need access to a MIC instance, either your own or a demo environment from Telenor Connexion. In your instance, make sure you have a user with read and write privileges to the privilege objects you want to access.

Preparation

In this Getting Started guide, you will authenticate to our Cloud REST API and then use some endpoints for creating and fetching resources. All of the endpoints in the Cloud REST API require the x-api-key header to be set.

Get the x-api-key

  1. Follow the Getting Started guide to get the manifest. Alternatively, log in to App Board and navigate to Settings >> About. The value shown for “Cloud Rest API” is the base of the API URL.
  2. Using the ApiGatewayRootUrl from the manifest or the info from App Board, call <ApiGatewayRootUrl>/prod/metadata/manifest. The response will contain the ApiKey.

Example for demo.mic.telenorconnexion.com

  1. https://wrd4rfaqo1.execute-api.eu-west-1.amazonaws.com/Prod/manifest/?hostname=demo.mic.telenorconnexion.com
  2. https://195cms8yb6.execute-api.eu-west-1.amazonaws.com/prod/metadata/manifest

1. Authenticate

We will begin by doing an unauthenticated POST request against /auth/login . In the request, we will provide our login credentials in JSON. The only parameter required for unauthenticated requests is the x-api-key header. This request will return a valid token for us to use in further requests.

Example request

Headers

{
  "x-api-key": "2d4b7d8a5e37460e93b1fc8a45d44043afcb8506"
}

Body


{
  "userName": "yourUserName",
  "password": "yourPassword"
}

Example response

Body

{
  "user": {
    "data": {},
    "domainPath": "/",
    "userName": "yourUserName",
    "roleName": "ReadWrite",
    "firstName": "FirstName",
    "lastName": "LastName",
    "email": "example@example.com",
    "domainName": "root"
  },
  "credentials": {
    "identityId": "<omitted>",
    "token": "<omitted>",
    "refreshToken": "<omitted>"
  }
}

The token and domainName properties are the important ones for this Getting Started guide. We will use them in the following requests.

2. Create thing type

Now that we have authenticated against the API, it’s time to call an authenticated endpoint. Let’s begin by creating a thing type. A thing type is a group or category of things. A thing will always belong to one and only one thing type.

Required role: ReadWrite
Required privilege: ThingType.CREATE on the specified domain

API Endpoint: [POST] : /thingtypes

Request

Headers

  • Authorization : The Authorization token returned from /auth/login
  • x-api-key : The API Key to identify the request

Body

  • id : The id of the thing type, must fulfil regular expression /^[a-z0-9-_]+$/. required
  • domain : The id of the domain that the thing type should belong to. We got the domain in the response from /auth/login. required
  • label : The label describing the thing type. required
  • description : A longer description of the thing.

Example payload

{
    "id": "lights",
    "domain": "root",
    "label": "Lights",
    "description": "Light switches"
}

Response

  • id : The id of the thing type.
  • domain : The id of the domain that the thing type belongs to.
  • label : The label describing the thing type.
  • description : A longer description of the thing.

If your response was successful, we can continue to the next step.

3. Create thing

Now that we successfully created a thing type in the previous step, we can continue by creating a thing.

Required role: ReadWrite

Creates a new thing and a corresponding thing certificate.

API Endpoint: [POST] : /things

Request

Headers

  • Authorization : The Authorization token returned from /auth/login
  • x-api-key : The API Key to identify the request

Body

  • thingName : The id to give the new thing.
  • thingType : The id of the thing type that you created earlier. required
  • domain : The id of the domain that the thing should belong to. required

Example payload

{
    "thingName": "MyThing",
    "thingType": "lights",
    "domain": "root",
}

Response

  • thingName : The id of the created thing.
  • thingType : The id of the thing type that the created thing belongs to.
  • domain : The id of the domain that the created thing belongs to.
  • createdAt : The time when the thing was created.
  • createdBy : The user name of the user that created the thing.

4. Get a thing

Now that we have created a thing type and a thing, we can do our first GET request to fetch our newly created thing.

Required role: Read
Required privilege: Things

API Endpoint: [GET] : /things

Request

Headers

  • Authorization : The Authorization token returned from /auth/login
  • x-api-key : The API Key to identify the request

Query Parameters

  • thingName : The thingName from the response in the previous step. required

Example request

GET : {{baseUrl}}/things?thingName=00004268

Response

  • thingName : The id of the requested thing.
  • thingType : The id of the thing type that the requested thing belongs to. optional
  • domain : The domain that the requested thing belongs to. optional
    • id : The id of the domain.
    • name : The name of the domain.
    • description : A longer description of the domain.
    • data : Custom data about the domain (see the Domain API for more information).
  • domainTopic : The domain topic of the requested thing. optional

5. Report data to the thing

Let’s report some data to our thing.

Note: Using the REST API to report data to your thing is not the usual way to do it. Normally you use MQTT to report. But for this Getting Started guide we will use the REST API.

Required role: ReadWrite

API Endpoint: [PUT] : /things/resources

Request

Headers

  • Authorization : The Authorization token returned from /auth/login
  • x-api-key : The API Key to identify the request

Body

  • thingName : The name of the thing. Use the value from the response to your GET request. required
  • thingType : The thing type of the thing. Use the value from the response to your GET request. required
  • resources[]:
    • name : The resource name. required
    • value : The resource value to set. required

Example payload

{
    "thingType": "383",
    "thingName": "00004268",
    "resources": [
        {
            "name": "SomeResourceName",
            "value": 10
        }
    ]
}

Response

Status: 200 OK

6. Fetch new data

Finally we can fetch our thing again, including its shadow. We will be able to see the resources we created on the thing in the previous step.

Required role: Read
Required privilege: Things

API Endpoint: [GET] : /things

Request

Headers

  • Authorization : The Authorization token returned from /auth/login
  • x-api-key : The API Key to identify the request

Query Parameters

  • thingName : The name of the thing. Use the same value from your previous GET request. required
  • attributes : Comma separated list of attributes to retrieve. For this tutorial we only ask for the shadow.

Example request

GET : {{baseUrl}}/things?thingName=00004268&attributes=shadow

Response

  • thingName : The id of the requested thing.
  • shadow : The shadow of the requested thing.

Conclusion

Congratulations! You have now done some basic requests using the MIC REST API. Check out the documentation for more examples and available endpoints.