HTTP

This page describes HTTP Connectivity in more detail

If a device communicates over HTTP with akenza, an HTTP connector has to be setup and assigned to a data flow.

After creation, a secret is generated which has to be provided in the request. Both the secret and the device ID are set as query params in the HTTP request.

Send an HTTP Uplink

POST https://data-gateway.akenza.io/v3/capture?secret={uplinkSecret}&deviceId={deviceId}

The body can be any JSON object.

Query Parameters

Name	Type	Description
timestamp (optional)	string	The timestamp of the event (ISO-8601 formatted), defaults to the current time if not provided
topic (optional)	string	The data topic ("default" will be used if not provided)
uplinkSecret	string	The uplink secret used to authenticate the request (it is recommended to use the x-uplink-secret header instead)
deviceId	string	The physical device ID

Headers

Name	Type	Description
Content-Type	string	application/json
x-uplink-secret	string	The uplink secret used to authenticate the request
x-device-id	string	The physical device ID

200

{
    "id": "UUID",
    "timestamp": "ISO-8601 date string",
    "message": "uplink received"
}

Array Uplinks

The HTTP connectivity also supports the processing of array uplinks (not just a JSON property which is an array but the whole request body).

There are minimal differences when processing such an uplink in the script.

Refer to the example event for array uplinks in the Scripting section for more details.

Support for using secret and device id in the header

Requests can be submitted by using secret and device id in the header. The header key should be x-uplink-secret and x-device-id. The value of the header is the secret of the device connector and the physical device id. Both values can be found on the Device Detail Page within API-Configuration or in the uplink URL.

DeviceId Templating

The device id can be parsed from the request body using a JSON path by enabling the setting when creating an HTTP device connector.

• $ The root element to query. This starts all path expressions.

• $.<propertyName> dot-notated property names

Examples:

• $.macAddress

• $.sensorMessages[0].sensorId

Note that always the first match is used from the body template: e.g. using a template like $.sensorMessages[0].sensorId, multiple messages in the same uplink by different devices are therefore not supported.

Plain HTTP endpoint

Use the endpoint http://plain.data-gateway.akenza.io if your device does not support HTTPS. We do not recommend to use this option as your data will be transmitted in plain text.