IoT Edge Connect API v1

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

Learn more:


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.

Get 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:

Topic filter Publishers Subscribers
company/model/%c Empty *

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:

Topic filter Publishers Subscribers
company/model/year * Empty

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:

Topic filter Publishers Subscribers
company/model/year Pub1 Sub1

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:

Topic filter Publishers Subscribers
company/model/%u Empty *
company/model/+ Pub1 Empty

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.

Topic filter Publishers Subscribers
company/%c/model Pub1 Empty
company/+/model Empty Sub1

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.

Operation Method Endpoint
List reserved namespaces GET /dcp-api/v1/namespaces{?size,page,hostnames}
Reserve a namespace POST /dcp-api/v1/namespaces
List all reserved namespaces GET /dcp-api/v1/namespaces/search{?global,match,detail}
Remove a namespace DELETE /dcp-api/v1/namespaces/{namespace}
List all namespace configurations GET /dcp-api/v1/namespaces/{namespace}/configurations
Create a namespace configuration POST /dcp-api/v1/namespaces/{namespace}/configurations
Get a namespace configuration GET /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}
Update a namespace configuration PUT /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}
Delete a namespace configuration DELETE /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}
List versions of a namespace configuration GET /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}/versions
Create a version of a namespace configuration POST /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}/versions
Deactivate a version of a namespace configuration PUT /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}/versions/active{?activation-state}
Activate a version of a namespace configuration PUT /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}/versions/{version}{?activation-state}
List all operations for configuration versions GET /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}/versions/activations

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.

GET /dcp-api/v1/namespaces{?size,page,hostnames}

Sample: /dcp-api/v1/namespaces?size=50&page=2&hostnames=sample.hostname.com%2Cexample.hostname.com

Parameter Type Sample Description
Optional query parameters
hostnames String sample.hostname.com,example.hostname.com A list of comma-delimited hostnames that you want to retrieve reserved namespaces for. These hostnames may be associated with multiple properties within your account.
page Integer 2 The number of the page with the number of namespaces to list specified in size. Page numbers start at zero.
size Integer 50 The number of namespaces per page.

Status 200 application/json

Object type: Reservation

Download schema: reservationsRS.json

Response body:

[
    {
        "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.

POST /dcp-api/v1/namespaces

Content-Type: application/json

Download schema: namespaceReservationRQ.json

Request body:

{
    "namespace": "company1"
}

Status 201

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.

GET /dcp-api/v1/namespaces/search{?global,match,detail}

Sample: /dcp-api/v1/namespaces/search?global=false&match=company1%2A&detail=true

Parameter Type Sample Description
Optional query parameters
detail Boolean true Whether to show connection details for the namespaces in the user’s account.
global Boolean false Whether to search for reserved namespaces in all accounts or in the user’s account only.
match String company1* A search of string matching content. You can use the wildcard character * to search for unspecified content.

Status 200 application/json

Object type: Reservation

Download schema: reservationsRS.json

Response body:

[
    {
        "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.

DELETE /dcp-api/v1/namespaces/{namespace}

Sample: /dcp-api/v1/namespaces/company1

Parameter Type Sample Description
URL path parameters
namespace String company1 The name of a namespace.

Status 200

List all namespace configurations

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

GET /dcp-api/v1/namespaces/{namespace}/configurations

Sample: /dcp-api/v1/namespaces/company1/configurations

Parameter Type Sample Description
URL path parameters
namespace String company1 The name of a namespace.

Status 200 application/json

Object type: ConfigurationVersion

Download schema: namespacesRS.json

Response body:

[
    {
        "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.

POST /dcp-api/v1/namespaces/{namespace}/configurations

Sample: /dcp-api/v1/namespaces/company1/configurations

Content-Type: application/json

Object type: Configuration

Download schema: namespaceConfigurationRQ.json

Request body:

{
    "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"
            ]
        }
    ]
}
Parameter Type Sample Description
URL path parameters
namespace String company1 The name of a namespace.

Status 202

Get a namespace configuration

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

GET /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}

Sample: /dcp-api/v1/namespaces/company1/configurations/na

Parameter Type Sample Description
URL path parameters
namespace String company1 The name of a namespace.
jurisdiction Enumeration na The name of a jurisdiction. The following options are available: na for North America, eu for Europe, jp for Japan, cn for China, sk for South Korea, br for Brazil, or xw for the rest of the world.

Status 200 application/json

Object type: ConfigurationVersion

Download schema: namespaceConfigurationRS.json

Response body:

{
    "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.

PUT /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}

Sample: /dcp-api/v1/namespaces/company1/configurations/na

Content-Type: application/json

Object type: Configuration

Download schema: namespaceConfigurationUpdateRQ.json

Request body:

{
    "acls": [
        {
            "topicFilter": "/car/#",
            "publishers": [
                "car"
            ],
            "subscribers": []
        },
        {
            "topicFilter": "/cars/#",
            "publishers": [
                "cars"
            ],
            "subscribers": [
                "proc1",
                "proc2"
            ]
        },
        {
            "topicFilter": "/cells/#",
            "publishers": [
                "cars"
            ],
            "subscribers": [
                "proc1"
            ]
        }
    ]
}
Parameter Type Sample Description
URL path parameters
namespace String company1 The name of a namespace.
jurisdiction Enumeration na The name of a jurisdiction. The following options are available: na for North America, eu for Europe, jp for Japan, cn for China, sk for South Korea, br for Brazil, or xw for the rest of the world.

Status 202

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.

DELETE /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}

Sample: /dcp-api/v1/namespaces/company1/configurations/na

Parameter Type Sample Description
URL path parameters
namespace String company1 The name of a namespace.
jurisdiction Enumeration na The name of a jurisdiction. The following options are available: na for North America, eu for Europe, jp for Japan, cn for China, sk for South Korea, br for Brazil, or xw for the rest of the world.

Status 200

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.

GET /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}/versions

Sample: /dcp-api/v1/namespaces/company1/configurations/na/versions

Parameter Type Sample Description
URL path parameters
namespace String company1 The name of a namespace.
jurisdiction Enumeration na The name of a jurisdiction. The following options are available: na for North America, eu for Europe, jp for Japan, cn for China, sk for South Korea, br for Brazil, or xw for the rest of the world.

Status 200 application/json

Object type: Activation

Download schema: activationsRS.json

Response body:

[
    {
        "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.

POST /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}/versions

Sample: /dcp-api/v1/namespaces/company1/configurations/na/versions

Parameter Type Sample Description
URL path parameters
namespace String company1 The name of a namespace.
jurisdiction Enumeration na The name of a jurisdiction. The following options are available: na for North America, eu for Europe, jp for Japan, cn for China, sk for South Korea, br for Brazil, or xw for the rest of the world.

Status 201 application/json

Download schema: activationVersionRS.json

Response body:

{
    "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.

PUT /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}/versions/active{?activation-state}

Sample: /dcp-api/v1/namespaces/company1/configurations/na/versions/active?activation-state=deactivated

Parameter Type Sample Description
URL path parameters
namespace String company1 The name of a namespace.
jurisdiction Enumeration na The name of a jurisdiction. The following options are available: na for North America, eu for Europe, jp for Japan, cn for China, sk for South Korea, br for Brazil, or xw for the rest of the world.
Required query parameters
activation-state Enumeration deactivated Specify deactivated as a keyword to deactivate the active configuration version.

Status 200 application/json

Download schema: alreadyDeactivatedRS.json

Response body:

{
    "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.

PUT /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}/versions/{version}{?activation-state}

Sample: /dcp-api/v1/namespaces/company1/configurations/na/versions/5?activation-state=activated

Parameter Type Sample Description
URL path parameters
namespace String company1 The name of a namespace.
jurisdiction Enumeration na The name of a jurisdiction. The following options are available: na for North America, eu for Europe, jp for Japan, cn for China, sk for South Korea, br for Brazil, or xw for the rest of the world.
version Integer 5 The configuration version that you want to activate.
Required query parameters
activation-state Enumeration activated Specify activated as a keyword to activate the specified configuration version.

Status 200 application/json

Download schema: alreadyActivatedRS.json

Response body:

{
    "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.

GET /dcp-api/v1/namespaces/{namespace}/configurations/{jurisdiction}/versions/activations

Sample: /dcp-api/v1/namespaces/company1/configurations/na/versions/activations

Parameter Type Sample Description
URL path parameters
namespace String company1 The name of a namespace.
jurisdiction Enumeration na The name of a jurisdiction. The following options are available: na for North America, eu for Europe, jp for Japan, cn for China, sk for South Korea, br for Brazil, or xw for the rest of the world.

Status 200 application/json

Object type: Activation

Download schema: activationsRS.json

Response body:

[
    {
        "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:

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.

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

Member Type Required Description
Reservation: The reservation JSON object specifies the reserved namespace.
namespace String The name of a reserved namespace.
owner Reservation.owner The owner of a namespace reservation.
reserved String The date of a namespace reservation.
Reservation.owner: The owner of a namespace reservation.
accountId String The account ID of the user who reserved this namespace.
createdBy String The name of the user who reserved this namespace.

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

Member Type Required Description
Configuration: The configuration JSON object specifies the configuration that you want to create for the specified namespace and jurisdiction.
acls Configuration.acls[] A list of access control rules for the configuration. Indicates users or clients that can publish or subscribe to specified topics. See access control lists.
jurisdiction Enumeration The jurisdiction that the configuration applies to. The following options are available: na for North America, eu for Europe, jp for Japan, cn for China, sk for South Korea, br for Brazil, or xw for the rest of the world.
Configuration.acls[]: A list of access control rules for the configuration. Indicates users or clients that can publish or subscribe to specified topics. See access control lists.
publishers Array A list of authorization group names. Indicates users or clients that have permission to publish messages to the topic referenced in topicFilter. With identity topic filters, use * to match a client or user identifier. See authorization group wildcard.
subscribers Array A list of authorization group names. Indicates users or clients that have permission to subscribe to the topic referenced in topicFilter. With identity topic filters, use * to match a client or user identifier. See authorization group wildcard.
topicFilter String The path to the topic that you want to authorize publishers and subscribers to. It is either an absolute path or a wildcarded path. In wildcarded topic filters, use + to match a single level and # to match multiple levels. See topic filter wildacrds and identity topic filters guidelines.

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

Member Type Description
ConfigurationVersion: The configuration JSON object specifies the configuration associated with the specified namespace and jurisdiction.
acls ConfigurationVersion.acls[] A list of access control rules for the configuration. Indicates users or clients that can publish or subscribe to specified topics. See access control lists.
jurisdiction Enumeration The jurisdiction to which the configuration applies. The following options are available: na for North America, eu for Europe, jp for Japan, cn for China, sk for South Korea, br for Brazil, or xw for the rest of the world.
namespace String The name of the namespace that the configuration applies to.
storage Integer Read-only. The amount of storage in megabytes that the namespace can use.
topic-expiry Integer Read-only. The number of days for the topic to expire.
ConfigurationVersion.acls[]: A list of access control rules for the configuration. Indicates users or clients that can publish or subscribe to specified topics. See access control lists.
publishers Array A list of authorization group names. Indicates users or clients that have permission to publish messages to the topic referenced in topicFilter. With identity topic filters, use * to match a client or user identifier. See authorization group wildcards.
subscribers Array A list of authorization group names. Indicates users or clients that have permission to subscribe to the topic referenced in topicFilter. With identity topic filters, use * to match a client or user identifier. See authorization group wildcard.
topicFilter String The path to the topic that you want to authorize publishers and subscribers to. It is either an absolute path or a wildcarded path. In wildcarded topic filters, use + to match a single level and # to match multiple levels. See topic filter wildacrds and identity topic filters guidelines.

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

Member Type Description
Activation: The activation JSON object specifies the configuration version that you activated or deactivated for the specified namespace and jurisdiction.
activationStatus Enumeration The status of the operation specified in operationType. The following options are available: NEW for an operation that has been created but not initiated, PENDING for an operation that is in the process of being performed, DEPLOYED for an operation that has successfully been performed, OBSOLETE for an operation that has been made obsolete by the validation server, ABORTED for an operation request that has been rejected, FAILED for an operation request that failed while being processed, or UNAVAILABLE for a server error. Try to repeat the last attempted operation for this configuration version or contact your account representative for support.
createdAt Integer A unix epoch timestamp in milliseconds. The most recent timestamp indicates the most recently created configuration version.
createdBy String The name of the user who created the configuration version.
jurisdiction Enumeration The jurisdiction where the configuration version was activated or deactivated. The following options are available: na for North America, eu for Europe, jp for Japan, xw for the rest of the world, cn for China, sk for South Korea, br for Brazil, or xw for the rest of the world.
namespace String The name of the namespace that the configuration version was created for.
operationType Enumeration The type of the operation performed for the configuration version. The following options are available: ACTIVATION for an activation of the configuration version or DEACTIVATION for a deactivation of the configuration version, or N/A if neither of the operations was performed on the configuration version.
version String The version of the namespace configuration.

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:

Code Description
200 The operation was successful.
201 Resource successfully created.
400 Malformed request. For example, from failing to meet the full set of schema requirements when POSTing a new resource.
403 Access is forbidden.
404 Resource not found.
409 Conflict with current state of resource.
415 Unsupported media type.
500 Internal server error.
503 Service is temporarily unavailable.

Last modified: 10/17/2019