Reserve namespaces and configure them for topic-based publish-subscribe messaging.

Learn more:

• Internet of Things (IoT): OTA Updates

• Download this API’s RAML and JSON schema descriptors.

Overview

IoT Edge Connect uses the Akamai Platform to provide communication and data processing for millions of connected devices. It is a scalable, reliable, and distributed real-time publish-subscribe mechanism that organizes data into logical categories called topics.

IoT Edge Connect has two interfaces: the message queuing telemetry transport (MQTT) and HTTP interfaces. Together these create a logical system that deploys across multiple geographic jurisdictions.

• MQTT interface. Provides an MQTT brokering service to publish messages to and read messages from topics. It also provides topic-based filtering by distributing all incoming messages to users based on their subscribed topics.

• HTTP interface. Provides an HTTP mechanism to publish messages to and read messages from the topics processed by the MQTT interface.

The IoT Edge Connect API provides namespace configurations for both the MQTT and HTTP interfaces. It allows you to reserve namespaces and configure them in selected geographic jurisdictions. Within a configuration, you can specify a list of valid topics and define access control lists with authorization groups that can publish or subscribe to selected topics.

Who should use this API

Use this API if you want to create your own automated mechanism to manage your namespace configurations outside of the Luna interface.

With the IoT Edge Connect API, you can provide namespace configurations for the Akamai Platform to let users publish/subscribe to pre-defined, dynamically-created, and user-dedicated topics. This fully-managed service for MQTT and HTTP messaging enables real-time communication between IoT devices and data centers.

Topic support

Topics are a logical collection of messages in an IoT data stream. IoT Edge Connect can support static, dynamic, and identity topics. A namespace can support a pre-defined number of topics and allow dynamic and identity topics.

• Static topics. Topics that are pre-defined by the user. They are basic static lines of communication. Wildcard-based subscriptions are supported for static topics. In a namespace configuration, static topics are defined by relative paths.

• Dynamic topics. Topics that are dynamically created when the user subscribes or publishes to them. The user has a pre-defined contractual limit on the number of subscribers to a dynamic topic. Wildcard-based subscriptions are not supported for dynamic topics. In a namespace configuration, dynamic topics are defined by paths ending with *.

• Identity topics. Topics that define the only users who can subscribe to them. In a namespace configuration, identity topics are defined by paths ending with **.

In a namespace configuration, topics are structured in a hierarchy similar to folders and files in a file system. A topic level separator, in the form of the forward slash /, separates each level within a topic tree and provides a hierarchical structure to the topic name. Using this system, you can create user-friendly and self-descriptive naming structures.

Configure access control lists

To maintain proper security control over publishing and subscribing to topics, you need to define access control lists with topic authorization groups. For each topic, a list of publishers specifies groups that can publish messages to a topic, and a list of subscribers specifies groups that can read messages from this topic.

For each static or dynamic topic, you need to define at least one publisher and subscriber across access control lists.

For each identity topic, you need to define at least one publisher in an access control list.

Getting started

To configure this API for the first time:

• Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

• To enable this API, choose the API service named IoT Edge Connect, and set the access level to READ-WRITE.

Resources

This section provides details on the IoT Edge Connect API’s various operations and parameters.

This lists all conceptual objects that you deal with when interacting with the IoT Edge Connect API.

• Namespace. A globally reserved name that indicates a specific configuration. A namespace is a root path for all topics defined within a namespace configuration. It may indicate up to seven separate configurations, one active configuration per each jurisdiction.

• Jurisdiction. A geographically distributed group of servers to which the namespace configuration applies. Each jurisdiction is a separate subset of the Akamai Platform with its own processing, data, and configuration.

• Configuration. A configuration associated with a specific namespace and jurisdiction. Each configuration includes a list of topics and security rules specifying authorization groups that can publish and subscribe to the listed topics.

• Version. A version of a configuration created for a specific namespace and jurisdiction.

• Activation. A version of a configuration created for a specific namespace and jurisdiction and sent to the Akamai Platform.

The following workflow presents the steps required to configure a newly or previously reserved namespace.

1. Access the IoT Edge Connect API.

2. Reserve a namespace.

3. Create a namespace configuration.

4. Create a version of the namespace configuration.

5. Activate the version of the namespace configuration on the Akamai Platform.

API summary

Download the RAML descriptors for this API.

List reserved namespaces

This operation lists all namespaces reserved for the account of the user making the request, up to 100 namespaces on a page.

[
    {
        "namespace": "aCompany1",
        "reserved": "2018-02-21T13:39:51Z",
        "owner": {
            "createdBy": "aUser",
            "accountId": "ABC-123"
        }
    },
    {
        "namespace": "aCompany2",
        "reserved": "2018-02-23T09:26:27Z",
        "owner": {
            "createdBy": "aUser",
            "accountId": "ABC-123"
        }
    },
    {
        "namespace": "aCompany3",
        "reserved": "2018-02-23T09:26:36Z",
        "owner": {
            "createdBy": "aUser",
            "accountId": "ABC-123"
        }
    }
]

Reserve a namespace

This operation globally reserves a namespace.

{
    "namespace": "company1"
}

List all reserved namespaces

This operation lists up to 30 namespaces reserved for the account of the user making the request unless additional filtering parameters are specified.

[
    {
        "namespace": "aCompany1",
        "reserved": "2018-02-21T13:39:51Z",
        "owner": {
            "createdBy": "aUser",
            "accountId": "ABC-123"
        }
    },
    {
        "namespace": "aCompany2",
        "reserved": "2018-02-23T09:26:27Z",
        "owner": {
            "createdBy": "aUser",
            "accountId": "ABC-123"
        }
    },
    {
        "namespace": "aCompany3",
        "reserved": "2018-02-23T09:26:36Z",
        "owner": {
            "createdBy": "aUser",
            "accountId": "ABC-123"
        }
    }
]

Remove a namespace

This operation removes a previously reserved namespace. To remove a namespace, delete all configurations of this namespace across jurisdictions.

List all namespace configurations

This operation returns configurations across all jurisdictions for the namespace that you specified in the URL.

[
    {
        "namespace": "company1",
        "jurisdiction": "na",
        "storage": 100,
        "topic-expiry": 365,
        "topics": [
            "/cars/data/diagnostics",
            "/car/**",
            "/cells/*"
        ],
        "acls": [
            {
                "path": "/cars/*",
                "publishers": [
                    "cars"
                ],
                "subscribers": [
                    "proc1",
                    "proc2"
                ]
            },
            {
                "path": "/cells/*",
                "publishers": [
                    "cars"
                ],
                "subscribers": [
                    "proc1"
                ]
            }
        ]
    },
    {
        "namespace": "company2",
        "jurisdiction": "eu",
        "storage": 50,
        "topic-expiry": 365,
        "topics": [
            "/cars/data/diagnostics",
            "/car/**",
            "/cells/*"
        ],
        "acls": [
            {
                "path": "/cars/*",
                "publishers": [
                    "cars"
                ],
                "subscribers": [
                    "proc1",
                    "proc2"
                ]
            },
            {
                "path": "/cells/*",
                "publishers": [
                    "cars"
                ],
                "subscribers": [
                    "proc1"
                ]
            }
        ]
    }
]

Create a namespace configuration

This operation creates a configuration for the namespace that you specified in the URL of the request and the jurisdiction that you specified in the body of the request.

{
    "jurisdiction": "na",
    "topics": [
        "/cars/data/diagnostics",
        "/car-1",
        "/car-2",
        "/car-dynamic-topic/*"
    ],
    "acls": [
        {
            "path": "/cars/*",
            "publishers": [
                "publishers"
            ],
            "subscribers": [
                "subscribers1",
                "subscribers2"
            ]
        },
        {
            "path": "/car-dynamic*",
            "publishers": [
                "car-publishers"
            ]
        },
        {
            "path": "/car-dynamic*",
            "subscribers": [
                "car-subscribers"
            ]
        },
        {
            "path": "/car-?",
            "publishers": [
                "car-sub-pub"
            ]
        },
        {
            "path": "/car-?",
            "subscribers": [
                "car-sub-pub"
            ]
        }
    ]
}

Get a namespace configuration

This operation returns the configuration for the namespace and jurisdiction that you specified in the URL of the request.

{
    "namespace": "company1",
    "jurisdiction": "na",
    "storage": 100,
    "topic-expiry": 7,
    "topics": [
        "/cars/data/diagnostics",
        "/car-identity-topic/**",
        "/cells-dynamic-topic/*"
    ],
    "acls": [
        {
            "path": "/cars/*",
            "publishers": [
                "cars"
            ],
            "subscribers": [
                "proc1",
                "proc2"
            ]
        },
        {
            "path": "/cells/*",
            "publishers": [
                "cars"
            ]
        },
        {
            "path": "/cells/*",
            "subscribers": [
                "proc1"
            ]
        }
    ]
}

Update a namespace configuration

This operation updates the configuration for the namespace and jurisdiction that you specified in the URL of the request.

{
    "topics": [
        "/car/**",
        "/cars/data/diagnostics",
        "/cells/*"
    ],
    "acls": [
        {
            "path": "/car/*",
            "publishers": [
                "car"
            ],
            "subscribers": []
        },
        {
            "path": "/cars/*",
            "publishers": [
                "cars"
            ],
            "subscribers": [
                "proc1",
                "proc2"
            ]
        },
        {
            "path": "/cells/*",
            "publishers": [
                "cars"
            ],
            "subscribers": [
                "proc1"
            ]
        }
    ]
}

Delete a namespace configuration

This operation removes all versions of the configuration for the namespace and jurisdiction that you specified in the URL of the request. To remove a configuration, deactivate the active version of this configuration.

List versions of a namespace configuration

This operation returns all versions of the configuration for the namespace and jurisdiction that you specified in the URL of the request. It also provides information about the users who created the configuration versions, times when the configuration versions were created, and operation details.

[
    {
        "createdBy": "aUser",
        "createdAt": 1521627657888,
        "namespace": "company1",
        "jurisdiction": "eu",
        "version": "1",
        "activationStatus": "DEPLOYED",
        "operationType": "ACTIVATION"
    },
    {
        "createdBy": "aUser",
        "createdAt": 1521627827115,
        "namespace": "company1",
        "jurisdiction": "eu",
        "version": "2",
        "activationStatus": "DEPLOYED",
        "operationType": "ACTIVATION"
    },
    {
        "createdBy": "aUser",
        "createdAt": 1521627890172,
        "namespace": "company1",
        "jurisdiction": "eu",
        "version": "2",
        "activationStatus": "PENDING",
        "operationType": "DEACTIVATION"
    }
]

Create a version of a namespace configuration

This operation creates a version of the configuration for the namespace and jurisdiction that you specified in the URL of the request.

{
    "version": "1"
}

Deactivate a version of a namespace configuration

This operation deactivates the active configuration for the namespace and jurisdiction that you specified in the URL of the request.

{
    "alreadyDeactivated": false
}

Activate a version of a namespace configuration

This operation activates a specified version of the configuration for the namespace and jurisdiction that you specified in the URL of the request.

{
    "alreadyActivated": false
}

List all operations for configuration versions

This operation returns all activations and deactivations of configuration versions for the namespace and jurisdiction that you specified in the URL of the request. It also provides information about the users who created the configuration versions, times when the configuration versions were created, and operation details.

[
    {
        "createdBy": "aUser",
        "createdAt": 1521627657888,
        "namespace": "company1",
        "jurisdiction": "eu",
        "version": "1",
        "activationStatus": "DEPLOYED",
        "operationType": "ACTIVATION"
    },
    {
        "createdBy": "aUser",
        "createdAt": 1521627827115,
        "namespace": "company1",
        "jurisdiction": "eu",
        "version": "2",
        "activationStatus": "DEPLOYED",
        "operationType": "ACTIVATION"
    },
    {
        "createdBy": "aUser",
        "createdAt": 1521627890172,
        "namespace": "company1",
        "jurisdiction": "eu",
        "version": "2",
        "activationStatus": "PENDING",
        "operationType": "DEACTIVATION"
    }
]

Data

This section details the JSON objects that the IoT Edge Connect API provides as data.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Reservation

The reservation JSON object specifies the reserved namespace.

Download schema: reservationRS.json

Sample GET response:

[
    {
        "namespace": "aCompany1",
        "reserved": "2018-02-21T13:39:51Z",
        "owner": {
            "createdBy": "aUser",
            "accountId": "ABC-123"
        }
    },
    {
        "namespace": "aCompany2",
        "reserved": "2018-02-23T09:26:27Z",
        "owner": {
            "createdBy": "aUser",
            "accountId": "ABC-123"
        }
    },
    {
        "namespace": "aCompany3",
        "reserved": "2018-02-23T09:26:36Z",
        "owner": {
            "createdBy": "aUser",
            "accountId": "ABC-123"
        }
    }
]

Reservation members

Configuration

The configuration JSON object specifies the configuration that you want to create for the specified namespace and jurisdiction.

Download schema: namespaceConfigurationRQ.json

Sample POST request:

{
    "jurisdiction": "na",
    "topics": [
        "/cars/data/diagnostics",
        "/car-1",
        "/car-2",
        "/car-dynamic-topic/*"
    ],
    "acls": [
        {
            "path": "/cars/*",
            "publishers": [
                "publishers"
            ],
            "subscribers": [
                "subscribers1",
                "subscribers2"
            ]
        },
        {
            "path": "/car-dynamic*",
            "publishers": [
                "car-publishers"
            ]
        },
        {
            "path": "/car-dynamic*",
            "subscribers": [
                "car-subscribers"
            ]
        },
        {
            "path": "/car-?",
            "publishers": [
                "car-sub-pub"
            ]
        },
        {
            "path": "/car-?",
            "subscribers": [
                "car-sub-pub"
            ]
        }
    ]
}

Configuration members

ConfigurationVersion

The configuration JSON object specifies the configuration associated with the specified namespace and jurisdiction.

Download schema: namespaceConfigurationRS.json

Sample GET response:

{
    "namespace": "company1",
    "jurisdiction": "na",
    "storage": 100,
    "topic-expiry": 7,
    "topics": [
        "/cars/data/diagnostics",
        "/car-identity-topic/**",
        "/cells-dynamic-topic/*"
    ],
    "acls": [
        {
            "path": "/cars/*",
            "publishers": [
                "cars"
            ],
            "subscribers": [
                "proc1",
                "proc2"
            ]
        },
        {
            "path": "/cells/*",
            "publishers": [
                "cars"
            ]
        },
        {
            "path": "/cells/*",
            "subscribers": [
                "proc1"
            ]
        }
    ]
}

ConfigurationVersion members

Activation

The activation JSON object specifies the configuration version that you activated or deactivated for the specified namespace and jurisdiction.

Download schema: activationRS.json

Sample GET response:

[
    {
        "createdBy": "aUser",
        "createdAt": 1521627657888,
        "namespace": "company1",
        "jurisdiction": "eu",
        "version": "1",
        "activationStatus": "DEPLOYED",
        "operationType": "ACTIVATION"
    },
    {
        "createdBy": "aUser",
        "createdAt": 1521627827115,
        "namespace": "company1",
        "jurisdiction": "eu",
        "version": "2",
        "activationStatus": "DEPLOYED",
        "operationType": "ACTIVATION"
    },
    {
        "createdBy": "aUser",
        "createdAt": 1521627890172,
        "namespace": "company1",
        "jurisdiction": "eu",
        "version": "2",
        "activationStatus": "PENDING",
        "operationType": "DEACTIVATION"
    }
]

Activation members

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

If you encounter an error, the IoT Edge Connect API responds with an appropriate data object that explains it. This sample shows a validation error where type provides a link where you can find out more about this error type, and title provides a descriptive label for the overall problem. It also includes an optional errors array that lists potentially more than one problem detected in the request.

{
    "type": "/dcp-api/error-types/ACL_PATH_CAN_NOT_BE_NULL",
    "title": "Problems parsing JSON",
    "errors": [
        {
            "type": "/dcp-api/error-types/ACL_PATH_CAN_NOT_BE_NULL",
            "title": "must not be null",
            "fieldName": "acls",
            "errorCode": "acl_path_can_not_be_null"
        }
    ],
    "errorCode": "validation_failed"
}

HTTP status codes

The IoT Edge Connect API responds with the following range of status codes:

Last modified: 2/5/2019