HTTP Device API

• Overview
• Base connection
  • HTTP path structure
• Prerequisites
• Data collection
  • Send data samples
  • Send plain data samples
• Metadata
  • Get all metadata keys request
  • Get metadata request
  • Full metadata update
  • Partial metadata update
  • Delete metadata keys
• Command execution
  • Request pending commands
  • Report command execution result
• Configuration
  • Configuration resource request
  • Report applied configuration request
• Software OTA
  • Software resource request
  • Report applied software update request
• Binary data upload
  • Get upload token

Written by Andrew Pasika

Overview

HTTP provides a standardized way for devices to communicate with Kaa server over the Internet. It allows devices to send requests for data or perform actions, and receive responses from servers.

HTTP transport is very similar to MQTT, except:

• communication is synchronous and follows a standard HTTP request-response pattern
• there is no support for asynchronous server push
• the supported HTTP request method is POST
• there is no need in a request ID at the end of the resource path or special response topics due to the native request-response support in HTTP

Base connection

HTTP requests can be tested on the public Kaa Cloud installation.

• HTTPS host: https://cloud.kaaiot.com/kpc (recommended one). The default port is 443
• HTTP host: http://cloud.kaaiot.com/kpc. The default port is 80

HTTP path structure

HTTP path structure:

{base_url}/kp1/{app_version_name}/{extension_instance_name}/{endpoint_token}/{resource_path}[/{request_id}]

where:

Every MQTT topic consists of next parts:

• {base_url} - Is base URL for HTTP device connectivity, e.g., https://cloud.kaaiot.com/kpc.
• kp1 - Is constant and is the reserved prefix for the Kaa Protocol version 1.
• {app_version_name} - The application version name where the endpoint is registered.
• {extension_instance_name} - Is a name that uniquely identifies an extension the message is destined to (every device connectivity feature is backed by specific extension). It can be dcx that implements Data Collection feature, epmx that implements Endpoint Metadata Management feature, cex that implements Command Execution feature, etc.
• {endpoint_token} - Is an endpoint token that uniquely identifies the endpoint, e.g. JTjdbENzHh. Decoupling endpoint tokens from IDs makes tokens disposable. You can revoke a lost or leaked endpoint token at any moment and issue a new one, retaining the same digital twin of your device with the same endpoint ID.
• {resource_path} is an extension-specific resource path that exposes some IoT functionality to endpoints. For example, Data collection feature (dcx extension) has /json resource path that allows endpoints to push telemetry data into the platform; Endpoint Metadata Management (epmx extension) has /update/keys for updating endpoint metadata attributes, etc. Below we will list more examples of extensions and their resource paths.
• {request_id} - This could be a random number between 1 and 99. Square brackets [/{request_id}] means that request ID is optional. In the MQTT request/response pattern section you will find the purpose of request ID.

Prerequisites

In the below section you can find cURL examples of communication with Kaa platform. To run these examples, export $APP_VERSION and $ENDPOINT_TOKEN with your application version and endpoint token respectively:

export APP_VERSION={app_version_name}
export ENDPOINT_TOKEN={endpoint_token}

You can also download Postman collection.

Data collection

Send data samples

POST https://cloud.kaaiot.com/kpc/kp1/{app_version_name}/dcx/{endpoint_token}/json

curl https://cloud.kaaiot.com/kpc/kp1/$APP_VERSION/dcx/$ENDPOINT_TOKEN/json --data '{"temperature": 21}'

Publishes telemetry data to the platform in JSON format. This supports both single and batched messages sent as an array. Historical data is stored in two databases. For fast access to raw data, it’s stored in InfluxDB and is accessible via the time series REST API. Aggregated data is stored in OpenSearch, which operates on top of ElasticSearch, and can be accessed via the analytics REST API or Kibana.

Payload schema:

{
  "$schema": "http://json-schema.org/schema#",
  "title": "2/DCP request schema",
  "type": "array"
}

Payload example for single data sample:

{
  "temperature": 21,
  "humidity": 73,
  "location": {
    "lat": 34.1340258,
    "lon": -118.3238652
  }
}

Use JSON array in order to send multiple data samples in one MQTT message. In the example below there is a batched payload with a predefined timestamp and two nested location JSON objects. Pay attention to the “ts” field, which is the timestamp for a sample and should be configured in Device management -> Applications -> your application -> “epts” (Kaa component that is responsible for time series processing). The “location” object should be configured as a custom Time series to value mapping in time series settings. The analytics storage may require you to specify the mapping to parse the string as a date. This can be configured in Data transformation -> Mappings.

Payload example for batch payload:

[
  {
    "ts": "2019-04-26T15:41:07+0000",
    "temperature": 21,
    "humidity": 73,
    "location": {
      "lat": 34.1340258,
      "lon": -118.3238652
    }
  },
  {
    "ts": "2019-04-26T16:41:07+0000",
    "temperature": 21.5,
    "humidity": 67,
    "location": {
      "lat": 34.1340258,
      "lon": -118.3238652
    }
  }
]

Send plain data samples

POST https://cloud.kaaiot.com/kpc/kp1/{app_version_name}/dcx/{endpoint_token}/plain/{metric_name}

curl https://cloud.kaaiot.com/kpc/kp1/$APP_VERSION/dcx/$ENDPOINT_TOKEN/plain/temperature --data '200'

Publish telemetry data to the platform in a plain format. Optionally, you can specify units in the value that will be mapped under the ${metric-name}-unit key. NOTE: It is required to enable Relaxed resource path validation under the Device management -> Applications -> your application -> “dcx” (Kaa component that is responsible for raw data samples processing).

Payload schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": [
    "number",
    "string"
  ]
}

Payload example:

200

Metadata

Get all metadata keys request

POST https://cloud.kaaiot.com/kpc/kp1/{app_version_name}/epmx/{endpoint_token}/get/keys

curl https://cloud.kaaiot.com/kpc/kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/get/keys

Get all endpoint metadata keys.

Response schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "10/EPMP get metadata keys response: a set of endpoint metadata keys",
  "type": "array",
  "items": {
    "type": "string",
    "pattern": "^[a-zA-Z0-9_]+$",
    "description": "Endpoint metadata key name"
  },
  "uniqueItems": true
}

Response example:

[
  "name",
  "location",
  "deviceModel"
]

Get metadata request

POST https://cloud.kaaiot.com/kpc/kp1/{app_version_name}/epmx/{endpoint_token}/get

curl https://cloud.kaaiot.com/kpc/kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/get

Get all endpoint metadata.

Response schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "10/EPMP get metadata response: a set of EP metadata key-value pairs in JSON object representation",
  "type": "object",
  "patternProperties": {
    "^[a-zA-Z0-9_]+$": {}
  },
  "additionalProperties": false
}

Response example:

{
  "name": "Device name",
  "deviceModel": "new model"
}

Full metadata update

POST https://cloud.kaaiot.com/kpc/kp1/{app_version_name}/epmx/{endpoint_token}/update

curl https://cloud.kaaiot.com/kpc/kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/update --data '{"deviceModel": "example model"}'

Update endpoint metadata with a set of key-value pairs in JSON object representation. See below for partial metadata update

Payload schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "10/EPMP update metadata request: a set of EP metadata key-value pairs in JSON object representation",
  "type": "object",
  "minProperties": 1,
  "patternProperties": {
    "^[a-zA-Z0-9_]+$": {}
  },
  "additionalProperties": false
}

Payload example:

{
  "deviceModel": "example model",
  "name": "Sensor 1"
}

Partial metadata update

POST https://cloud.kaaiot.com/kpc/kp1/{app_version_name}/epmx/{endpoint_token}/update/keys

curl https://cloud.kaaiot.com/kpc/kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/update/keys --data '{"deviceModel": "new model"}'

Update endpoint metadata with a set of key-value pairs in JSON object representation.

Payload schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "10/EPMP update metadata request: a set of EP metadata key-value pairs in JSON object representation",
  "type": "object",
  "minProperties": 1,
  "patternProperties": {
    "^[a-zA-Z0-9_]+$": {}
  },
  "additionalProperties": false
}

Payload example:

{
  "deviceModel": "new model"
}

Delete metadata keys

POST https://cloud.kaaiot.com/kpc/kp1/{app_version_name}/epmx/{endpoint_token}/delete/keys

curl https://cloud.kaaiot.com/kpc/kp1/$APP_VERSION/epmx/$ENDPOINT_TOKEN/delete/keys --data '["location"]'

Delete endpoint metadata keys.

Payload schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "10/EPMP delete metadata keys request",
  "type": "array",
  "items": {
    "type": "string",
    "pattern": "^[a-zA-Z0-9_]+$",
    "description": "Endpoint metadata key name"
  },
  "minItems": 1,
  "uniqueItems": true
}

Payload example:

[
  "location",
  "areaId"
]

Command execution

Request pending commands

POST https://cloud.kaaiot.com/kpc/kp1/{app_version_name}/cex/{endpoint_token}/command/{command_type}

curl https://cloud.kaaiot.com/kpc/kp1/$APP_VERSION/cex/$ENDPOINT_TOKEN/command/switch --data '{}'

Request pending (scheduled for execution) commands for the endpoint.

Payload schema:

{
  "$schema": "http://json-schema.org/schema#",
  "title": "11/CEP command request schema",
  "type": "object",
  "properties": {
    "observe": {
      "type": "boolean",
      "description": "Whether to send upcoming command for this endpoint."
    }
  },
  "additionalProperties": false
}

Payload example

{
  "observe": true
}

Response schema:

{
  "$schema": "http://json-schema.org/schema#",
  "title": "11/CEP command request schema",
  "type": "object",
  "properties": {
    "observe": {
      "type": "boolean",
      "description": "Whether to send upcoming command for this endpoint."
    }
  },
  "additionalProperties": false
}

Response example:

{
  "observe": true
}

Report command execution result

POST https://cloud.kaaiot.com/kpc/kp1/{app_version_name}/cex/{endpoint_token}/result/{command_type}

curl https://cloud.kaaiot.com/kpc/kp1/$APP_VERSION/cex/$ENDPOINT_TOKEN/result/switch --data '[{"id": 1,"statusCode": 200}]'

Report command execution result to the platform.

Payload schema:

{
  "$schema": "http://json-schema.org/schema#",
  "title": "11/CEP result request schema",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "description": "ID of the command."
      },
      "statusCode": {
        "type": "integer",
        "description": "Status code of the command execution. Based on HTTP status codes."
      },
      "reasonPhrase": {
        "type": "string",
        "description": "Intended to give a short textual description of the status code."
      },
      "payload": {
        "description": "A command result payload to be interpreted by the caller."
      }
    },
    "required": [
      "id",
      "statusCode"
    ],
    "additionalProperties": false
  }
}

Payload example:

[
  {
    "id": 1,
    "statusCode": 200,
    "reasonPhrase": "Ok",
    "payload": {
      "engine_on": true
    }
  }
]

Configuration

Configuration resource request

POST https://cloud.kaaiot.com/kpc/kp1/{app_version_name}/cmx/{endpoint_token}/config/json

curl https://cloud.kaaiot.com/kpc/kp1/$APP_VERSION/cmx/$ENDPOINT_TOKEN/config/json --data '{}'

Request configuration by ID.

Payload schema

{
  "$schema": "http://json-schema.org/schema#",
  "title": "7/CMP configuration request schema",
  "type": "object",
  "properties": {
    "configId": {
      "type": "string",
      "description": "Identifier of the currently applied configuration"
    },
    "observe": {
      "type": "boolean",
      "description": "Whether the endpoint is interested in observing its configuration"
    }
  },
  "additionalProperties": false
}

Payload example:

{}

Response schema:

{
  "$schema": "http://json-schema.org/schema#",
  "title": "7/CMP configuration request schema",
  "type": "object",
  "properties": {
    "configId": {
      "type": "string",
      "description": "Identifier of the currently applied configuration"
    },
    "observe": {
      "type": "boolean",
      "description": "Whether the endpoint is interested in observing its configuration"
    }
  },
  "additionalProperties": false
}

Response example:

{
  "id": 42,
  "configId": "97016dbe8bb4adff8f754ecbf24612f2",
  "statusCode": 200,
  "reasonPhrase": "ok",
  "config": {
    "key": "value",
    "array": [
      "value2"
    ]
  }
}

Report applied configuration request

POST https://cloud.kaaiot.com/kpc/kp1/{app_version_name}/cmx/{endpoint_token}/applied/json

curl https://cloud.kaaiot.com/kpc/kp1/$APP_VERSION/cmx/$ENDPOINT_TOKEN/applied/json --data '{"configId": "97016dbe8bb4adff8f754ecbf24612f2"}'

Report applied configuration to the platform. Configuration can be rejected by sending the status code 400 or higher.

Payload schema:

{
  "$schema": "http://json-schema.org/schema#",
  "title": "7/CMX applied configuration request schema",
  "type": "object",
  "properties": {
    "configId": {
      "type": "string",
      "description": "Identifier of the applied configuration"
    },
    "statusCode": {
      "type": "number",
      "description": "Status code based on HTTP status codes",
      "default": 200
    },
    "reasonPhrase": {
      "type": "string",
      "description": "Human-readable string explaining the cause of an error (if any)"
    }
  },
  "required": [
    "configId"
  ],
  "additionalProperties": false
}

Payload example:

{
  "configId": "97016dbe8bb4adff8f754ecbf24612f2"
}

Software OTA

Software resource request

POST https://cloud.kaaiot.com/kpc/kp1/{app_version_name}/cmx_ota/{endpoint_token}/config/json

curl https://cloud.kaaiot.com/kpc/kp1/$APP_VERSION/cmx_ota/$ENDPOINT_TOKEN/config/json --data '{}'

Request the new firmware version for the endpoint.

Payload schema:

{
  "$schema": "http://json-schema.org/schema#",
  "type": "object",
  "properties": {
    "observe": {
      "type": "boolean",
      "description": "Whether to send upcoming firmware updates for this endpoint."
    }
  },
  "additionalProperties": false
}

Payload example:

{
  "observe": true
}

Response schema:

{
  "$schema": "http://json-schema.org/schema#",
  "type": "object",
  "properties": {
    "observe": {
      "type": "boolean",
      "description": "Whether to send upcoming firmware updates for this endpoint."
    }
  },
  "additionalProperties": false
}

Response example

{
  "observe": true
}

Report applied software update request

POST https://cloud.kaaiot.com/kpc/kp1/{app_version_name}/cmx_ota/{endpoint_token}/applied/json

curl https://cloud.kaaiot.com/kpc/kp1/$APP_VERSION/cmx/$ENDPOINT_TOKEN/applied/json --data '{"configId": "0.0.2"}'

Report applied software update to the platform. Software update can be rejected by sending the status code 400 or higher.

Payload schema:

{
  "$schema": "http://json-schema.org/schema#",
  "title": "7/CMX applied configuration request schema",
  "type": "object",
  "properties": {
    "configId": {
      "type": "string",
      "description": "Identifier of the applied configuration"
    },
    "statusCode": {
      "type": "number",
      "description": "Status code based on HTTP status codes",
      "default": 200
    },
    "reasonPhrase": {
      "type": "string",
      "description": "Human-readable string explaining the cause of an error (if any)"
    }
  },
  "required": [
    "configId"
  ],
  "additionalProperties": false
}

Payload example:

{
  "configId": "0.0.2"
}

Binary data upload

Get upload token

POST https://cloud.kaaiot.com/kpc/kp1/{app_version_name}/bcx/{endpoint_token}/token

curl https://cloud.kaaiot.com/kpc/kp1/$APP_VERSION/bcx/$ENDPOINT_TOKEN/token

Request the upload token for the endpoint to be used in “x-auth-token” HTTP header for uploading binary blob data.

Response schema:

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "Access token to be used in \"x-auth-token\" header for upload binary blob data."
    }
  },
  "additionalProperties": false
}

Response example:

{
  "token": "2222"
}