Edge Data Stream API v1

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

Durable sliding buffer for publish/subscribe messaging

Learn more:

Internet of Things (IoT): Edge Connect
Download this API’s RAML and JSON schema descriptors.

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.

API concepts

There are few basic concepts that are important for this API.

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

This operation reads a set of messages from a single topic.

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

Sample: /api/v1/buffer/topics/topic1?offset=500&limit=50

Parameter	Type	Sample	Description
URL parameters
`topic`	String	`topic1`	The name of the topic to read from.
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

Response Body:

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

Get Messages for Groups

This operation 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/topic1/groups/group1?limit=50&ack=true

Parameter	Type	Sample	Description
URL parameters
`topic`	String	`topic1`	The name of the topic to read from.
`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

Response Body:

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

Get a Retained Message

This operation reads the latest retained message from a single topic.

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

Sample: /api/v1/buffer/retained/topic1

Parameter	Type	Sample	Description
URL parameters
`topic`	String	`topic1`	The name of the topic to read from.

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.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

✓	Member is required in requests, or always present in responses, even if its value is empty or `null`.
○	Member is optional, and may be omitted in some cases.

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
`messages`	MessageBlock.messages[]	○	Messages read from the topic.
`token`	Integer	○	The group token.
`MessageBlock.messages[]`: Messages read from the topic.
`clientId`	String	✓	Identifies each message’s publisher.
`payload`	String	✓	The message in a base64 format.
`topicSequenceNumber`	Integer	✓	The sequence number of a message in a topic.

Errors

This section provides details on the data object that reflects 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.

Last modified: 5/14/2019