IoT Edge Data Stream API v1

Use this tool with IoT Edge Connect to read aggregated messages from topics.

Learn more:

Overview

Edge Data Stream is a durable sliding buffer for messages, created as a supplementary tool for IoT Edge Connect.

Use this API to:

  • Combine messages sent by multiple publishers into a single stream.

  • Bulk read large streams of data.

  • Retain the ordering used by the publishing service.

Get started

Use this API alongside the IoT Edge Connect product.

Use the authentication method you’ve configured in your Edge Connect property.

  • For JWT, you need to pass the token in your request header. Unless you’ve specified otherwise, the header name is X-Akamai-DCP-Token.

  • If you selected Mutual Authentication, your authentication is validated alongside your connection to the service. You don’t need to pass any authentication information alongside your request.

This API does not follow Akamai’s standard system of provisioning API tokens within Akamai Control Panel.

API concepts

These concepts clarify the API’s messaging resources:

  • Topic. An ordered collection of messages.

  • Message block. A message or group of messages sent from a single topic.

  • Message. An individual object stored in a topic.

  • Consumer group. Multiple subscribers sharing a single subscription. All group members receive alternating messages, with each message sent only to one group member. It’s most commonly used for load balancing.

  • Retained message. It’s an MQTT message automatically sent to the subscriber at the moment of subscribing. It is most commonly used for configuration or status updates.

Resources

This section provides details on the Edge Data Stream API’s various operations and parameters.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Get messages GET /api/v1/buffer/topics/{topic}{?offset,limit}
Get messages for groups GET /api/v1/buffer/topics/{topic}/groups/{groupId}{?limit,ack}
Get a retained message GET /api/v1/buffer/retained/{topic}

Get messages

Reads a set of messages from a single topic.

GET /api/v1/buffer/topics/{topic}{?offset,limit}

Sample: /api/v1/buffer/topics/diagnostics%252Fmake%252Fmodel?offset=500&limit=50

Parameter Type Sample Description
URL path parameters
topic String diagnostics%2Fmake%2Fmodel The full, URL-encoded path of the topic to read from. This example reads from diagnostics/make/model.
Optional query parameters
limit Integer 50 The maximum number of messages to read.
offset Integer 500 The sequence number of the first message to retrieve.

Status 200 application/json

Object type: MessageBlock

Download schema: message-block.json

Response body:

{
    "messages": [
        {
            "clientId": "client1",
            "payload": "YWJj",
            "topicSequenceNumber": 1
        },
        {
            "clientId": "client3",
            "payload": "aDEj",
            "topicSequenceNumber": 2
        }
    ]
}

Get messages for groups

Reads a set of messages from a single topic for the provided consumer group.

GET /api/v1/buffer/topics/{topic}/groups/{groupId}{?limit,ack}

Sample: /api/v1/buffer/topics/diagnostics%252Fmake%252Fmodel/groups/group1?limit=50&ack=true

Parameter Type Sample Description
URL path parameters
topic String diagnostics%2Fmake%2Fmodel The full, URL-encoded path of the topic to read from. This example reads from diagnostics/make/model.
groupId String group1 The name of the consumer group.
Optional query parameters
ack Boolean true The message read acknowledgement.
limit Integer 50 The maximum number of messages to read.

Status 200 application/json

Object type: MessageBlock

Download schema: message-block.json

Response body:

{
    "messages": [
        {
            "clientId": "client1",
            "payload": "YWJj",
            "topicSequenceNumber": 1
        },
        {
            "clientId": "client3",
            "payload": "aDEj",
            "topicSequenceNumber": 2
        }
    ],
    "token": 1234
}

Get a retained message

Reads the latest retained message from a single topic.

GET /api/v1/buffer/retained/{topic}

Sample: /api/v1/buffer/retained/diagnostics%252Fmake%252Fmodel

Parameter Type Sample Description
URL path parameters
topic String diagnostics%2Fmake%2Fmodel The full, URL-encoded path of the topic to read from. This example reads from diagnostics/make/model.

Status 200 application/octet-stream

Response body:

VderKUx2VMqaASsbloD4AWYnnMz3ASDrQhQ

Data

This section provides details on the API’s JSON objects. The basic response is a MessageBlock.

MessageBlock

A collection of messages and metadata.

Download schema: message-block.json

Sample GET response:

{
    "messages": [
        {
            "clientId": "client1",
            "payload": "YWJj",
            "topicSequenceNumber": 1
        },
        {
            "clientId": "client3",
            "payload": "aDEj",
            "topicSequenceNumber": 2
        }
    ]
}

MessageBlock members

Member Type Required Description
MessageBlock: A collection of messages and metadata.
messages MessageBlock.messages[] ○ Messages read from the topic.
token Integer ○ The group token.
MessageBlock.messages[]: Messages read from the topic.
clientId String ✓ Identifies the publisher of the message.
payload String ✓ The message in base64 format.
topicSequenceNumber Integer ✓ The sequence number of a message in a topic.

Errors

This section provides details on the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

The API reports errors with an HTML message.

<HTML><HEAD>
<TITLE>Access Denied</TITLE>
</HEAD><BODY>
<H1>Access Denied</H1>

You don't have permission to access "http:example.com;" on this server.<P>
Reference&#12341234
</BODY>
</HTML>

HTTP status codes

The API responds with the following set of HTTP status codes for both success and failure scenarios.

Code Description
200 The operation was successful.
401 Authentication failure.
402 Database error.
403 Access is forbidden.
404 Resource not found.
500 Internal server error.