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

Before using the API for the first time:

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.

Operation Method Endpoint
List reserved namespaces GET /dcp-api/v1/namespaces{?size,page}
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}

Sample: /dcp-api/v1/namespaces?size=50&page=2

Parameter Type Sample Description
Optional query parameters
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

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

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

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 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 parameters
namespace String company1 The name of a namespace.

Status 200 application/json

Response Body:

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

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

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

Content-Type: application/json

Request Body:

{
    "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"
            ]
        }
    ]
}
Parameter Type Sample Description
URL 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 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

Response Body:

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

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

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

Content-Type: application/json

Request Body:

{
    "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"
            ]
        }
    ]
}
Parameter Type Sample Description
URL 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 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 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

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

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 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 204

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

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

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 to be present, regardless of whether its value is empty or null.
Member is optional, and may be omitted in some cases.

Reservation

The reservation JSON object provides information about 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
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 reservation JSON object provides information about 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

Member Type Required Description
acls Configuration.acls[] A list of access control rules for the configuration. Indicates users or clients that can publish or subscribe to specified topics.
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.
topics Array A list of all topics. Relative paths indicate static topics, paths ending with ** indicate identity topics, and paths ending with * indicate dynamic topics. A topic path must be between 1 and 255 characters. For each static or dynamic topic, specify at least one publisher and one subscriber. For each identity topic, specify at least one publisher and leave subscribers empty.
Configuration.acls[]: A list of access control rules for the configuration. Indicates users or clients that can publish or subscribe to specified topics.
path String The path of the topic to which you want to authorize publishers and subscribers. It is either a relative path indicating a static topic, or a wildcarded path indicating a topic or a group of topics. For wildcarded paths, use ? to match a single character and * to match any number of characters.
publishers Array A list of authorization group names. Indicates users or clients that have permission to publish messages to the topic referenced in path.
subscribers Array A list of authorization group names. Indicates users or clients that have permission to subscribe to the topic referenced in path.

ConfigurationVersion

The configuration JSON object provides information about 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

Member Type Required Description
acls ConfigurationVersion.acls[] A list of access control rules for the configuration. Indicates individual users or clients that can publish or subscribe to specified topics.
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 to which the configuration applies.
storage Integer Read-only. The amount of storage in megabytes that the namespace can use.
topic-expiry Integer Read-only. The number of days after which the topic expires.
topics Array A list of all topics. Relative paths indicate static topics, paths ending with * indicate dynamic topics, and paths ending with ** indicate identity topics.
ConfigurationVersion.acls[]: A list of access control rules for the configuration. Indicates individual users or clients that can publish or subscribe to specified topics.
path String The path of the topic to which publishers and subscribers are authorized. It is either a relative path indicating a static topic, or a wildcarded path indicating a topic or a group of topics. For wildcarded paths, ? matches a single character and * matches any number of characters.
publishers Array A list of authorization group names. Indicates users or clients that have permission to publish messages to the topic referenced in path.
subscribers Array A list of authorization group names. Indicates users or clients that have permission to subscribe to the topic referenced in path.

Activation

The activation JSON object provides information about 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 Required Description
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 for which the configuration version was created.
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",
    "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:

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 Too many requests. Service is temporarily unavailable.

Last modified: 7/30/2018