HTTP specification¶

The HTTP protocol of the Messaging API is ideal for short-lived connections between external clients (HTTP clients) and the DSH. The HTTP client can only receive retained messages from the DSH. This supports the scenario of devices that are in sleeping mode most of the time, wake up at a set time interval, make a connection, exchange data with the DSH, and go back to sleep again.

The Messaging API has the following endpoints and methods for HTTP:

Endpoint	Methods	Description
`data/v0/single`	POST, GET, DELETE	Act on the data of a single MQTT topic
`data/v0/multi`	POST	Fetch retained data from multiple MQTT topics

Through these endpoints, the HTTP has equivalent functionality to MQTT:

Publish a single value to an MQTT topic.
Subscribe to one or multiple MQTT topics. However, when you send a GET request, you can only query the Latest Value Store for retained data.
Unlike MQTT, HTTP doesn’t offer live updates of the data as it appears on the topics.

Tip

See Retained messages for more information.

data/v0/single¶

Use this endpoint to act on the data of a single MQTT topic.

POST¶

Use the “POST” method to publish data to an MQTT topic.

Request¶

POST data/v0/single/tt/<DSH-stream>/<topic>

You can use the following parameters in the request:

Parameter Description Default value

qos

The Quality of Service (QoS) defines the guarantee of delivery for a specific message. The concept is taken from MQTT. The Messaging API supports two levels for HTTP:

At most once (0): Guarantees a best-effort delivery. The recipient doesn't acknowledge that it received the message.
At least once (1): The sender stores the message until the receiver acknowledges that it received the message. It's possible for a message to be sent or delivered multiple times.

1

retained

Whether to mark the message as "retained":

The concept is taken from MQTT.
If an MQTT topic has a retained message, then a client receives that message immediately after they subscribe to that MQTT topic.
For each MQTT topic, the broker stores the latest retained message and the corresponding QoS.
Supported values are true or false.

true

Response¶

The DSH returns the following statuses:

Status	Description
200	The operation was successful.
400	The HTTP request has invalid properties.
401	The authorization header is missing or wrong.
403	The client isn't authorized to publish to the specified MQTT topic.
404	The MQTT topic path isn't supported: invalid MQTT topic layout or unknown DSH stream.
405	The method isn't supported: the Messaging API only supports POST, GET and DELETE for HTTP.
408	No request received in the first 10 seconds after the connection setup.
411	The `content-length` header is missing.
415	The media type isn't supported: use `text/plain`, `base64`, or `application/octet-stream`.
500	The service for the Messaging API is down.
505	The HTTP version isn't supported: use HTTP 1.1.

Example¶

RequestResponse

POST /data/v0/single/tt/weather/1/2/0/2/0/0/3/3/1/3/3/2/0/0/0/1 HTTP/1.1
User-Agent: <user-agent>
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ik1ZIE1RVFQgVE9LRU4ifQ.U0LWGERXajMqmXRbsYtLnlT26rqU4gZMQaU1Z_qmV7Q
Content-Type: application/json
Content-Length: 293
Connection: close

{
    "sunrise": 1617167648,
    "code": 800,
    "snow_3h": 0,
    "rain_3h": 0,
    "shortdesc": "Clear",
    "icon": "http://openweathermap.org/img/w/01d.png",
    "description": "clear sky",
    "winddir": 292,
    "pressure": 1021,
    "cloudcover": 0,
    "sunset": 1617214214,
    "temperature": 288.93,
    "humidity": 60,
    "windspeed": 0.45,
    "timestamp": 1617182232
}

HTTP/1.1 200 OK
Connection: Closed

GET¶

Use the “GET” method to fetch retained data from an MQTT topic.

Request¶

 GET data/v0/single/tt/<DSH-stream>/<topic>

In the “Accept” header, you can specify which data format the DSH should use in the response:

Accept: text/plain
Accept: base64
Accept: application/octet-stream

Response¶

The DSH returns the following statuses:

Status	Description
200	The operation was successful.
400	The HTTP request has invalid properties.
401	The authorization header is missing or wrong.
403	The client isn't authorized to subscribe to the specified MQTT topic.
404	The MQTT topic path isn't supported: no retained data, invalid MQTT topic layout, or unknown DSH stream.
405	The method isn't supported: the Messaging API only supports POST, GET and DELETE for HTTP.
408	No request received in the first 10 seconds after the connection setup.
500	The service for the Messaging API is down.
505	The HTTP version isn't supported: use HTTP 1.1.

Example¶

RequestResponse

GET /data/v0/single/tt/weather/1/2/0/2/0/0/3/3/1/3/3/2/0/0/0/1 HTTP/1.1
User-Agent: <user-agent>
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ik1ZIE1RVFQgVE9LRU4ifQ.U0LWGERXajMqmXRbsYtLnlT26rqU4gZMQaU1Z_qmV7Q
Host: 127.0.0.1
Accept: application/json
Connection: close

HTTP/1.1 200 OK
Content-Type: application/json
Connection: Closed
Content-Length: 293

{
    "sunrise": 1617167648,
    "code": 800,
    "snow_3h": 0,
    "rain_3h": 0,
    "shortdesc": "Clear",
    "icon": "http://openweathermap.org/img/w/01d.png",
    "description": "clear sky",
    "winddir": 292,
    "pressure": 1021,
    "cloudcover": 0,
    "sunset": 1617214214,
    "temperature": 288.93,
    "humidity": 60,
    "windspeed": 0.45,
    "timestamp": 1617182232
}

DELETE¶

Use the “DELETE” method to remove a retained message from the specified MQTT topic.

Request¶

DELETE data/v0/single/tt/<DSH-stream>/<topic>

Because of the MQTT specification, removing a message will propagate to all MQTT clients that have active subscriptions on that MQTT topic. They will receive the “delete” message.

Response¶

The DSH returns the following statuses:

Status	Description
200	The operation was successful.
400	The HTTP request has invalid properties.
401	The authorization header is missing or wrong.
403	The client isn't authorized to publish to the specified MQTT topic.
404	The MQTT topic path isn't supported: invalid MQTT topic layout or unknown DSH stream.
405	The method isn't supported: the Messaging API only supports POST, GET and DELETE for HTTP.
408	No request received in the first 10 seconds after the connection setup.
500	The service for the Messaging API is down.
505	The HTTP version isn't supported: use HTTP 1.1.

Example¶

RequestResponse

DELETE /data/v0/single/tt/weather/1/2/0/2/0/0/3/3/1/3/3/2/0/0/0/1 HTTP/1.1
User-Agent: <user-agent>
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ik1ZIE1RVFQgVE9LRU4ifQ.U0LWGERXajMqmXRbsYtLnlT26rqU4gZMQaU1Z_qmV7Q
Host: 127.0.0.1
Connection: close

HTTP/1.1 200 OK
Connection: Closed

data/v0/multi¶

Use this endpoint to fetch retained data from the Latest Value Store. This supports subscriptions to multiple MQTT topics in one single request. In other words, you can use:

Multiple topic filters
MQTT wildcard topics (+ and #)

POST¶

Use the “POST” method to fetch the retained data for multiple MQTT topics.

Request¶

POST data/v0/multi

The HTTP content-type header of the request must be “application/json”, and the JSON body must have the following schema:

{ 
"content-type": "text/plain" | "base64",
"topic-filters": [ "<topic-filter>", "<topic-filter>", … ]  
}

The content-type inside the JSON body specifies how the Messaging API needs to deliver the data. Options are:
- "content-type": "text/plain"
- "content-type": "base64"
The topic-filters can be a list of any valid MQTT-style topic filters, including wildcard characters (+ and #).

Response¶

The DSH returns the following statuses:

Status	Description
200	The operation was successful.
400	The HTTP request has invalid properties, or malformed JSON body.
401	The authorization header is missing or wrong.
403	The client isn't authorized to subscribe to the specified MQTT topic.
404	The MQTT topic path isn't supported: invalid MQTT topic layout or unknown DSH stream.
405	The method isn't supported: the Messaging API only supports POST for this endpoint.
408	No request received in the first 10 seconds after the connection setup.
411	The `content-length` header is missing.
415	The media type isn't supported: use `text/plain` or `base64`.
500	The service for the Messaging API is down.
505	The HTTP version isn't supported: use HTTP 1.1.

Example¶

RequestResponse

POST /data/v0/multi HTTP/1.1
User-Agent: <user-agent>
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ik1ZIE1RVFQgVE9LRU4ifQ.U0LWGERXajMqmXRbsYtLnlT26rqU4gZMQaU1Z_qmV7Q
Content-Type: application/json
Content-Length: 171
Connection: close

{
"content-type": "text/plain",
"topic-filters": [
    "/tt/weather/1/2/0/2/0/0/3/3/1/3/3/2/#",
    "/tt/weather/1/2/0/2/0/0/3/3/1/3/3/1/#",
    "/tt/weather/1/2/0/2/0/0/3/3/1/3/3/0/#"
]
}

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: . . .
Connection: Closed

[
{
    "topic": "/tt/weather/1/2/0/2/0/0/3/3/1/3/3/2/0/0/0/1",
    "payload" : "{ \"sunrise\": 1617167648, \"code\": 250, \"snow_3h\": 0, \"rain_3h\": 0, . . ."
},
{
    "topic": "/tt/weather/1/2/0/2/0/0/3/3/1/3/3/2/0/0/1/1",
    "payload" : "{ \"sunrise\": 1617167648, \"code\": 135, \"snow_3h\": 0, \"rain_3h\": 0, . . ."
},
{  
    "topic": "/tt/weather/1/2/0/2/0/0/3/3/1/3/3/1/0/0/0/0",
    "payload" : "{ \"sunrise\": 1617167648, \"code\": 765, \"snow_3h\": 0, \"rain_3h\": 0, . . ."
},
…
]