Adding dimensions from an API

If you are not ingesting your data using Platform Service , you can add dimensions to a device type using a REST API or through the Set up assets page on the user interfacce

About this task

Use the following REST API endpoint to add dimensions:

POST /entityType/{{entityTypeName}}/dimensional

Note: You must include Content-Type: application/json in the HTTP header.

A third-party application, such as Postman, can be used to make the REST API call. Postman is available to download at https://www.getpostman.com/.

Restriction: You cannot add dimensions to a device type that was simulated by using the device simulator or using the sample device type templates.

If you are ingesting data through Platform Service, you can add dimensions when you register a device. For more information, see Adding dimenions.

Steps

Complete these steps to add dimensions.

Step 1 - Gather API information

Before you use the API, gather the following information:

• Your API key and authentication token: Generate an API key and authentication token.
  1. From the user interface, go to the Services tab.
  2. Select Watson IoT Platform Service.
  3. Click View Details.
  4. Click View more.
  5. Save the API key and token for use.
• Your tenant ID: The tenant ID where you created the device type.
• The URL to use in the POST request: The protocol and environment where the API is placed, such as: http://api-{{geo_country_code}}.connectedproducts.internetofthings.ibmcloud.com/api/master/v1/{{tenant}}/.
• The country code for your geo: Use us, or uk, or de. If you are in the beta environment, use beta as the country code.
• The device type: The name of the device type that you want to update with dimensions.

Step 2 - Define the header

Define the following key value pairs for the header:

Step 3 - Define the JSON payload

Define the JSON payload for creating dimension types and values using the following format:

[
  {
    "id": "string",
    "name": "string",
    "type": "NUMBER", "BOOLEAN", or "LITERAL"
    "value": <literal>, <number>, or <TRUE or FALSE>
  }
]

Where id is the device ID, name is the name of the dimension you are creating, and value is the dimension value for the device.

Example:

[
  {
        "id": "car1",
        "name" : "FLEET",
        "type" : "NUMBER",
        "value" : 8
    },
    {
        "id": "car2",
        "name" : "FLEET",
        "type" : "NUMBER",
        "value" : 15
    },
    {
        "id": "car1",
        "name" : "COLOR",
        "type" : "LITERAL",
        "value" : "yellow"
    },
    {
        "id": "car2",
        "name" : "COLOR",
        "type" : "LITERAL",
        "value" : "red"
    }
]

The example shows dimension data for two entities, car1 and car2. Both entities are assigned a fleet number and a color.

Note Do not use reserved names, for example, SQL reserved words, as dimension names.

Step 4 - Make the REST API call

1. Sign in to Postman.
2. Click New > Request.
3. Assign a name to the request.
4. Select POST from the request drop-down.

5. Enter the URL in the URL field.
   Example:
   
   https://api-us.connectedproducts.internetofthings.ibmcloud.com/api/master/v1/Sample_Tenant/entityType/Sample_Robot_Type/dimensional
   

6. Select the Headers tab.

7. Enter the header key value pairs (see step 1):
8. Select the Body tab.
9. Enter the JSON payload for dimensions (see step 2).
10. Click Send.

Step 5 - Verify that the dimensions are added

1. Log in to the user interface.
2. In the side navigation, click Monitor.
3. On the Device types tab, select your device type and click View.
4. Select the Data tab.
5. Verify that the new dimensions are added.