# HTTP

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

<mark style="color:green;">`POST`</mark> `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                             |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

### 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.&#x20;

{% hint style="info" %}
Refer to the [example event for array uplinks](https://docs.akenza.io/akenza.io/reference/scripting#example-array-uplink-event) in the Scripting section for more details.
{% endhint %}

### 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:&#x20;

* `$.macAddress`&#x20;
* `$.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.&#x20;

### 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.