Learn more:

• Internet of Things (IoT): Edge Connect

• 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’s 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 that lets you 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 that lets you publish messages to and read messages from 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 paths to topics and define authorization groups that can publish or subscribe to these topics. You create topics by publishing or subscribing to them.

Who should use this API

Use this API if you want to create your own automated mechanism to manage your namespace configurations outside of Akamai Control Center.

With these namespace configurations, your users can leverage the Akamai Platform to publish messages to and read messages from specified topics. This fully managed service for MQTT and HTTP messaging enables real-time communication between IoT devices and data centers.

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.

IoT Edge Connect concepts

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 that the namespace configuration applies to. 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 topic filters and security rules specifying authorization groups that can publish and subscribe to the referenced 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.

• Topic. A UTF–8 string that represents an ordered collection of messages in an IoT data stream. It’s similar to a hierarchy of folders and files in a file system. A topic level slash (/) separates each level within a topic tree and provides a hierarchical structure to a topic.

• Topic filter. A path to a topic name that IoT Edge Connect uses to filter messages for all connected users and devices. It’s either an absolute path to one topic or a wildcarded path to one or more topics.

• ACL. A list of permissions attached to a topic. It consists of a topic filter and authorization groups specifying which groups of users and devices can publish and subscribe to the topic.

Topic filters

IoT Edge Connect API supports the following topic filters:

• Regular topic filter. Defines a specific line of communication. All authorized users and devices can subscribe and publish to the topic it represents. In an ACL configuration, a topic filter is defined by an absolute path. For example, company/model/year/version/.

• Device identity topic filter. Defines the only devices that can subscribe or publish to the topic it represents. In an ACL configuration, a device topic filter is defined by a path including %c that represents a single topic level and is a replacement for a client identifier. Only the devices with matching client identifiers can publish or subscribe to topics represented by such topic filters. For example, with this topic filter company/model/%c/version, the only devices that can publish or subscribe to the company/model/ABC123/version topic must have the ABC123 client identifier.

• User identity topic filter. Defines the only users who can subscribe or publish to the topic it represents. In an ACL configuration, a user identity topic filter is defined by a path including %u that represents a topic level and is a replacement for a user identifier. Only the users with matching user identifiers can publish or subscribe to topics represented by such topic filters. By default, devices belonging to one user have different client identifiers but share the same user identifier. By publishing a message to a topic represented by a user identity filter, a message is delivered to all devices sharing this particular user identifier. For example, with this topic filter company/model/%u/version, the only users that can publish or subscribe to the company/model/ABC123/version topic must have the ABC123 user identifier. Also, all devices that share the ABC123 user identifier can read a message from this topic.

Topic filter wildcards

You can use the following wildcards in a topic filter to broaden the range of topics that it represents:

• #. Use this multi level wildcard to match the parent and any number of child topic levels. You can use it either on its own or after a level separator /. It must be the last character in the path. For example, this topic filter company/model/year/# may represent these topics: company/model/year/version or company/model/year/user/price.

• +. Use this one-level wildcard to match a specific topic level. You can also use it at more than one topic level and together with the multi level wildcard. For example, this topic filter +/company/+/year/# may represent these topics: network/company/campaign/year/version or country/company/industry/year/software/price.

Authorization group wildcard

You can use the * wildcard in an ACL rule to authorize either any devices and users or any devices and users with specific identifiers to access the topic. The function of this wildcard depends on the topic filter that you use it with.

• For an identity topic filter, use * to authorize any device or user with an identifier that matches a topic level represented by %c or %u in the topic filter to access this topic.

For example:

Here the topic filter may represent the following topic company/model/ABC123. The ACL rule authorizes any device with the ABC123 client identifier to subscribe to this topic.

• For a regular topic filter, use * to authorize any device or user to access the topic.

For example:

Here the topic filter represents the following topic company/model/year. The ACL rule authorizes any device or user to publish to this topic.

Important: You shouldn’t use this wildcard with regular topic filters. You should only use this wildcard together with identity topic filters to authorize devices or users with specific identifiers.

Access control lists

To maintain proper security control over publishing and subscribing to topics, you need to define access control list rules.

• For a regular topic filter, specify one ACL rule with groups of publishers, subscribers, or both.

For example:

Here the topic filter represents the following topic company/model/year. The ACL rule authorizes any devices and users with the Pub1 authorization group to publish to the topic. It also authorizes any devices and users with the Sub1 authorization group to subscribe to this topic.

• For a user or device identity topic filter, specify two ACL rules with groups of publishers and subscribers defined separately in each rule. This way, you give access to the topic not only to devices or users with specific identifiers but also to groups of devices and users belonging to a specific authorization group. See Identity topic filters guidelines.

For example:

Here the topic filter may represent the following topic company/model/ABC123. The first ACL rule authorizes any user with the ABC123 user identifier to subscribe to the topic. The second ACL rule authorizes any user with the Pub1 authorization group to publish to this topic.

Here the topic filter may represent the following topic company/CDE123/model. The first ACL rule authorizes any device with the Pub1 authorization group and the CDE123 client identifier to publish to the topic. The second ACL rule authorizes any device with the Sub1 authorization group to subscribe to this topic.

Identity topic filters guidelines

An ACL rule with an identity topic filter needs a complementary ACL rule with a wildcarded topic filter. In the wildcarded topic filter, the * wildcard replaces the topic level that matches a device or user identifier. This replacement allows specific authorization groups to access topics that otherwise require device or user identifiers to be accessed. When creating this pair of ACL rules, follow these guidelines:

1. In the first ACL rule, specify an identity topic filter where %c or %u replaces a topic level that matches a client or user identifier.

2. For the topic filter’s publishers or subscribers, either:

   • Specify at least one authorization group. Note: Within this group, the only devices or users that can access this topic have identifiers that match the topic level represented by %c or %u in the topic filter.

   • Use * to authorize any devices or users with identifiers that match the topic level represented by %c or %u in the topic filter.

3. In the second ACL rule, specify a wildcarded topic filter where + replaces a topic level that matches a client or user identifier.

4. For the topic filter’s publishers or subscribers, either:

   • Specify at least one publisher authorization group if the first ACL rule authorizes a subscriber authorization group.

   • Specify at least one subscriber authorization group if the first ACL rule authorizes a publisher authorization group.

Important: Overlapping authorization groups for a pair of identity and + topic filters may result in unintended groups of devices or users being authorized to access the topic. You should always specify publisher and subscriber authorization groups for such a pair of topic filters in two separate ACL rules.

Resources

This section provides details on the IoT Edge Connect API’s various operations and parameters. It also presents the steps that you need to follow 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,
        "acls": [
            {
                "topicFilter": "/cars/#",
                "publishers": [
                    "cars"
                ],
                "subscribers": [
                    "proc1",
                    "proc2"
                ]
            },
            {
                "topicFilter": "/cells/#",
                "publishers": [
                    "cars"
                ],
                "subscribers": [
                    "proc1"
                ]
            }
        ]
    },
    {
        "namespace": "company2",
        "jurisdiction": "eu",
        "storage": 50,
        "topic-expiry": 365,
        "acls": [
            {
                "topicFilter": "/cars/#",
                "publishers": [
                    "cars"
                ],
                "subscribers": [
                    "proc1",
                    "proc2"
                ]
            },
            {
                "topicFilter": "/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. For ACL configuration guidelines, see access control lists and identity topic filters guidelines.

{
    "jurisdiction": "na",
    "acls": [
        {
            "topicFilter": "/cars/#",
            "publishers": [
                "publishers"
            ],
            "subscribers": [
                "subscribers1",
                "subscribers2"
            ]
        },
        {
            "topicFilter": "/car-dynamic/#",
            "publishers": [
                "car-publishers"
            ],
            "subscribers": [
                "car-subscribers"
            ]
        },
        {
            "topicFilter": "/car/+/one-level",
            "publishers": [
                "car-publishers"
            ]
        }
    ]
}

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,
    "acls": [
        {
            "path": "/cars/#",
            "publishers": [
                "cars"
            ],
            "subscribers": [
                "proc1",
                "proc2"
            ]
        },
        {
            "path": "/cells/#",
            "publishers": [
                "cars"
            ],
            "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. For ACL configuration guidelines, see access control lists and identity topic filters guidelines.

{
    "acls": [
        {
            "topicFilter": "/car/#",
            "publishers": [
                "car"
            ],
            "subscribers": []
        },
        {
            "topicFilter": "/cars/#",
            "publishers": [
                "cars"
            ],
            "subscribers": [
                "proc1",
                "proc2"
            ]
        },
        {
            "topicFilter": "/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",
    "acls": [
        {
            "topicFilter": "/cars/#",
            "publishers": [
                "publishers"
            ],
            "subscribers": [
                "subscribers1",
                "subscribers2"
            ]
        },
        {
            "topicFilter": "/car-dynamic/#",
            "publishers": [
                "car-publishers"
            ],
            "subscribers": [
                "car-subscribers"
            ]
        },
        {
            "topicFilter": "/car/+/one-level",
            "publishers": [
                "car-publishers"
            ]
        }
    ]
}

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,
    "acls": [
        {
            "path": "/cars/#",
            "publishers": [
                "cars"
            ],
            "subscribers": [
                "proc1",
                "proc2"
            ]
        },
        {
            "path": "/cells/#",
            "publishers": [
                "cars"
            ],
            "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",
    "errorCode": "validation_failed",
    "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"
        }
    ]
}

HTTP status codes

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

Last modified: 3/13/2019