Documentation

Mistake on this page? Email us

Connect API

Pelion Device Management Connect API allows web applications to communicate with devices. You can subscribe to device resources and read/write values to them. Device Management Connect allows connectivity to devices by queueing requests and caching resource values.

See Troubleshooting the APIs for information on status and error codes.

Version: 2
Host: https://api.us-east-1.mbedcloud.com

Endpoints

DeviceRequests

post /v2/device-requests/{device-id}
Send an async request to device Show more Show less

This API provides an interface to asynchronously call methods on a device.

The async-id is provided by the client, enabling the client to track the end-to-end flow with an identifier that is relevant to the end application. For example, a web application's session ID along with the device ID and the resource path could be used as the async-id. This also avoids any race conditions with the notification channel. All responses are sent through the currently configured notification channel as an AsyncIDResponse.

For GET methods, values may be fetched from an internal cache, instead of contacting the device.

The server queues requests if it cannot reach the device at the time of the request. The queue is limited to 20 requests. The queueing behaviour is affected by the retry and the expiry-seconds parameters. If the device is not reached, or the device fails to respond when the request is made, the server queues the request and retries within the given expiry period the next time the device contacts the server. The requests from the queue are delivered in the order of insertion, one at a time, and not concurrently.

One delivery attempt consist from protocol specific retrasmission logic, where is multiple trasmissions. In case of CoAP, the retrasmissions exponential backoff 2, 4, 8, 16 to 64 seconds, taking total over 2 minutes. If the device does not respond within this two-minute period, delivery fails, and the request is put back in the queue so long as the retry count is less than its maximum.

For a queue-mode device, the request delivery is not attempted immediately, but only when the device next time contacts the server.

If retries are exhausted or the expiry time has passed, then the server discards the request and sends an error in AsyncIDResponse. The retries could be exhausted, for example, if the device periodically contacts the server and receives the request from the queue, but then fails to respond back to the server.

On the other hand, the device might lose its network connectivity, and the requests in the queue might expire and get discarded before the device regains the connectivity.

You can write Notification Rules for a resource with PUT command. Please see example of the payload below.

{ "method": "PUT", "uri": "/5/0/1?lt=10&gt=60&pmax=120" }

POST method can be used to either execute or create resource on a LWM2M supporting device. When creating a resource, uri must refer to an object, and payload-b64 must be in LWM2M TLV format, as in the following example.

{ "method": "POST", "uri": "/123", "content-type": "application/vnd.oma.lwm2m+tlv", "payload-b64": "BwHFAnZhbHVl" }
Example URIs:
POST /v2/device-requests/015f2fa34d310000000000010030036c?async-id=123e4567-e89b-12d3-a456-426655440000
POST /v2/device-requests/015f2fa34d310000000000010030036c?async-id=123e4567-e89b-12d3-a456-426655440000&retry=2&expiry-seconds=7200

Example payload to read value from resource /5/0/1:
{ "method": "GET", "uri": "/5/0/1" }

Example payload to set notification rules for resource /5/0/1:
{ "method": "PUT", "uri": "/5/0/1?lt=10&gt=60&pmax=120" }

Example payload to write value "value1" to resource /5/0/1:
{ "method": "PUT", "uri": "/5/0/1?k1=v1&k2=v2", "accept": "text/plain", "content-type": "text/plain", "payload-b64": "dmFsdWUxCg==" }

Example payload to execute LWM2M resource /123/1/1:
{ "method": "POST", "uri": "/123/1/1" }

Immediate response:
202 Accepted

Examples of AsyncIDResponse, delivered via the notification channel:
{ "async-responses": [ { "id": "123e4567-e89b-12d3-a456-426655440000", "status": 200, "payload": "dmFsdWUxCg==", "ct": "text/plain", "max-age": 600 } ] }
{ "async-responses": [ { "id": "123e4567-e89b-12d3-a456-426655440000", "status": 504, "error": "TIMEOUT" } ] }
Path parameters
device-id (required)
Path Parameter — The device ID generated by Device Management.
format: uuid, 32 hexadecimal characters
Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json
Request body
body DeviceRequest (required)
Body Parameter — Device request to send.
Query parameters
async-id (required)
Query Parameter — The client-generated ID for matching the correct response delivered by notification.
format: 1-40 alphanumeric characters and dashes.
retry (optional)
Query Parameter — The count of retry transmissions of the request to the device, after initial transmission. For example, retry of two means three delivery attempts in total. If retries are exhausted, the request is discarded and an error is delivered in the AsyncIDResponse. Default value of retry is 0 for a non-queue-mode device and 2 for a queue-mode device.
minimum: 0
maximum: 10
expiry-seconds (optional)
Query Parameter — The time period during which the delivery is attempted, in seconds. If the device is not reachable within this period, the request is discarded and an error is delivered in the AsyncIDResponse. Default value of expiry-seconds is 2 hours for a non-queue-mode device and 3 days for a queue-mode device.
minimum: 60
maximum: 2592000
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
202 Accepted.
400 Bad request. Contains one of the errors RESOURCE_NOT_FOUND, DEVICE_NOT_CONNECTED, MALFORMED_JSON_CONTENT, MALFORMED_ASYNC_ID and QUEUE_IS_FULL String
401 Authentication failure.
404

Contains one of the following errors:

Error message Description
DEVICE_NOT_FOUND Device is not in Device reqistry. Either device has requestd register delete or device has not connected in time and expired.
URI_PATH_DOES_NOT_EXISTS The device does not have requested resource. Check the resource path is correct.
String

Endpoints

get /v2/endpoints/{device-id}
List the resources on an endpoint. Show more Show less

Retrieves resources cached by Device Management Connect. This call does not formulate a message to the device.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/endpoints/{device-id} \
-H 'Authorization: Bearer <api_key>'
Path parameters
device-id (required)
Path Parameter — A unique device ID for an endpoint. The ID must be an exact match. Do not use wildcards.
Return type
array[ Resource]
Example data
Content-Type: application/json
[ {
  "obs" : true,
  "rt" : "light_sensor",
  "type" : "text/plain",
  "uri" : "/sen/light"
} ]
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Successful response with an array of resources. array[Resource]
404 Endpoint not found.

Notifications

get /v2/notification/websocket-connect
(PREVIEW) Open the websocket. Show more Show less

(PREVIEW) A websocket channel can have only one active connection at a time. If a websocket connection for a channel exists and a new connection to the same channel is made, the connection is accepted and the older connection is closed.

Once the socket has been opened, it may be closed with one of the following status codes.

Code Description
1000 Socket closed by the client.
1001 Going away. Set when another socket opens on the used channel, the channel is deleted with a REST call, or the server is shutting down.
1008 Policy violation. Set when the API key is missing or invalid.
1011 Unexpected condition. Socket is closed with this status at an attempt to open a socket to a nonexistent channel (without a prior PUT request). This code is also used to indicate closing socket for any other unexpected condition in the server.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/notification/websocket-connect \
-H "Authorization:Bearer {apikey}" \
-H "Connection:upgrade" \
-H "Upgrade:websocket" \
-H "Sec-WebSocket-Version: 13" \
-H "Sec-WebSocket-Key: {base64nonce}" \
-N -I
Request headers
Connection (required)
Header Parameter — default: Upgrade
Upgrade (required)
Header Parameter — default: websocket
Sec-WebSocket-Protocol (optional)
Header Parameter — API key or user token must be present in the Sec-WebSocket-Protocol header if Authorization header cannot be provided: Sec-WebSocket-Protocol:"wss,pelion_ak_{api_key}". Refer to the notification service documentation for examples.
Origin (required)
Header Parameter — Originating host of the request.
Sec-WebSocket-Version (required)
Header Parameter — WebSocket version. Must be 13. default: 13
Sec-WebSocket-Key (required)
Header Parameter — The value of this header field must be a nonce consisting of a randomly selected 16-byte value that has been base64-encoded (see Section 4 of [RFC4648]). The nonce must be selected randomly for each connection.
Responses
status description schema
101 Switching protocols.
400 Required header(s) missing.
401 Unauthorized.
426 Upgrade required. Connect and/or Upgrade headers missing.
delete /v2/notification/pull
Delete notification Long Poll channel. Show more Show less
Deprecation Date:
Expected End of Life:
Long polling is deprecated and should be used for development purposes only.
Links:

Delete a notification Long Poll channel. This is required to change the channel from Long Poll to another type. Do not make a GET /v2/notification/pull call for two minutes after deleting the channel, because it can implicitly recreate the pull channel. You can also have some random responses with payload or 410 GONE with "CHANNEL_DELETED" as a payload or 200/204 until the old channel is purged.

Example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v2/notification/pull \
-H 'Authorization: Bearer <api_key>'
Responses
status description schema
200 Success. The body can contain "REMOVED" if it was deleted with this call or "ALREADY_DELETED" if it was deleted before and not purged yet.
401 Unauthorized.
delete /v2/notification/websocket
(PREVIEW) Delete websocket channel. Show more Show less

(PREVIEW) Delete a notification websocket channel bound to the API key. This is required to change the channel from websocket to another type.

Example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v2/notification/websocket \
-H 'Authorization: Bearer <api_key>'
Responses
status description schema
204 Successfully deleted.
401 Unauthorized.
403 Forbidden. The authorization token used is not an API key.
404 Websocket channel doesn't exist.
delete /v2/notification/callback
Delete callback URL. Show more Show less

Deletes the callback URL.

Example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v2/notification/callback \
-H 'Authorization: Bearer <api_key>'
Responses
status description schema
204 Successfully deleted.
401 Unauthorized.
403 Forbidden. The authorization token used is not an API key.
404 Callback URL does not exist.
get /v2/notification/channel
Get channel metadata. Show more Show less

Get channel delivery mechanism.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/notification/channel \
-H 'Authorization: Bearer <api_key>' \
Return type
Example data
Content-Type: application/json
{
  "delivery_mechanism" : "CALLBACK"
}
Responses
status description schema
200 Success. ChannelMetadata
404 Channel was not found.
get /v2/notification/callback
Check callback URL. Show more Show less

Shows the current callback URL if it exists.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/notification/callback \
-H 'Authorization: Bearer <api_key>'
Return type
Example data
Content-Type: application/json
{
  "serialization" : "{}",
  "headers" : "{\"authorization\" : \"f4b93d6e-4652-4874-82e4-41a3ced0cd56\"}",
  "url" : "https://www.example.com/my-webhook"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 URL found. Webhook
401 Unauthorized.
403 Forbidden. The authorization token used is not an API key.
404 The callback URL does not exist.
get /v2/notification/websocket
(PREVIEW) Get websocket channel information. Show more Show less

(PREVIEW) Returns 200 with websocket connection status, if websocket channel exists.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/notification/websocket \
-H 'Authorization: Bearer <api_key>'
Return type
Example data
Content-Type: application/json
{
  "serialization" : "{}",
  "queue_size" : 0,
  "status" : "disconnected"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Websocket found. WebsocketChannel
401 Unauthorized.
403 Forbidden. The authorization token used is not an API key.
404 No channel has been registered.
get /v2/notification/pull
Get notifications using Long Poll Show more Show less
Deprecation Date:
Expected End of Life:
Long polling is deprecated and should be used for development purposes only.
Links:

In this case, notifications are delivered through HTTP long poll requests. The HTTP request is kept open until one or more event notifications are delivered to the client, or the request times out (response code 204). In both cases, the client should open a new polling connection after the previous one closes. Only a single long polling connection per API key can be ongoing at any given time. We recommend using a persistent connection (Connection keep-alive header in the request) to avoid excess TLS handshakes.

The pull channel is implicitly created by the first GET call to /v2/notification/pull. It refreshes on each GET call. If the channel is not polled for a long time (10 minutes), it expires and is deleted. This means that no notifications will stay in the queue between polls. A channel can be also be deleted explicitly with a DELETE call.

Note: If you cannot have a public-facing callback URL, for example, when developing on your local machine, you can use long polling to check for new messages. However, long polling is deprecated and will likely be replaced in the future. It is meant only for experimentation, not commercial use. The proper method to receive notifications is a notification callback.

There can only be one notification channel per API key in Device Management Connect. If a notification channel of other type already exists for the API key, delete it before creating a long poll notification channel.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/notification/pull \
-H 'Authorization: Bearer <api_key>'
Return type
Example data
Content-Type: application/json
{
  "registrations" : [ {
    "q" : false,
    "original-ep" : "my-device-123",
    "ept" : "Light",
    "resources" : [ {
      "path" : "/sen/light",
      "ct" : "text/plain",
      "obs" : true,
      "rt" : "light_sensor",
      "if" : "sensor"
    } ],
    "ep" : "015f3850a657000000000001001002ab"
  } ],
  "reg-updates" : [ "" ],
  "async-responses" : [ {
    "ct" : "text/plain",
    "payload" : "My4zMQ==",
    "max-age" : "60",
    "id" : "9e3c96b8-c4d7-496a-ab90-cc732b9b560e",
    "error" : "TIMEOUT",
    "status" : 200
  } ],
  "notifications" : [ {
    "path" : "/sen/light",
    "ct" : "text/plain",
    "payload" : "My4zMQ==",
    "max-age" : "60",
    "ep" : "015f3850a657000000000001001002ab"
  } ],
  "de-registrations" : [ "015f3850a657000000000001001002ab" ],
  "registrations-expired" : [ "015f3850a657000000000001001002ab" ]
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Success. NotificationMessage
204 No new notifications.
400 Other type of channel already exists.
401 Unauthorized.
409 Conflict. Long poll request exists already.
410 Pull channel was deleted and waiting to be purged. This code is a result of incorrect client behavior (delete channel and then pull), which can prevent the creation of a callback channel after the pull channel is deleted. The channel can be (randomly) recreated by this call when deleted and not purged. This client behaviour can set the channel in an undefined state for some time. The channel may respond with 410 GONE or 200/204 codes randomly for some time. Finally, the channel enters a valid "channel exists" state.
put /v2/notification/callback
Register a callback URL. Show more Show less

Register a URL to which the server delivers notifications of changes to the subscribed resource. To push notifications, you must first place subscriptions. The maximum length of the URL, header keys, and values, all combined, is 400 characters.

Notifications are delivered as PUT requests to the HTTP server, which the client defines with a subscription server message. The given URL must be accessible, and respond to the PUT request with a response code of 200 or 204.

Device Management Connect tests the callback URL with an empty JSON payload {} when the URL is registered. Callback implementation does not support URL redirection. For more information on notification messages, see NotificationMessage.

Optional headers in a callback message:

You can set optional headers to a callback in a Webhook object. Device Management Connect includes the header and key pairs in the notification messages send them to callback URL. The callback URLs and headers are API key-specific.

One possible use for additional headers is checking the origin of a PUT request, as well as distinguishing the application (API key) to which the notification belongs.

Note: Only one callback URL per API key can be active. If you register a new URL while another one is active, it replaces the active one. There can be only one notification channel at a time. If another type of channel is already present, you need to delete it before setting the callback URL.

Expiration of a callback URL:

A callback can expire when Device Management cannot deliver a notification due to a connection timeout or an error response (4xx or 5xx). After each delivery failure, Device Management sets an exponential back off time and makes a retry attempt after that. The first retry delay is 1 second, then 2s, 4s, 8s, up to maximum delay of two minutes. The callback URL is removed if all retries fail within 24 hours. More about notification sending logic.

Supported callback URL protocols:

Currently, only HTTP and HTTPS protocols are supported.

HTTPS callback URLs:

When delivering a notification to an HTTPS based callback URL, Device Management Connect presents a valid client certificate to identify itself. The certificate is signed by a trusted certificate authorithy (GlobalSign) with a Common Name (CN) set to notifications.mbedcloud.com.

Configuration options:

The event notification channel provides configurations options defined in Serialization config.

Example:

This example command shows how to set your callback URL and API key. It also sets an optional header authorization. When Device Management Connect calls your callback URL, the call contains the authorization header with the defined value.

curl -X PUT https://api.us-east-1.mbedcloud.com/v2/notification/callback \
-H 'Authorization: Bearer <api_key>' \
-H 'content-type: application/json' \
-d '{
  "url": "{callback-url}",
  "headers": {"authorization": "f4b93d6e-4652-4874-82e4-41a3ced0cd56"},
  "serialization": {"type": "v2", "max_chunk_size": "100",
    "cfg": {"deregistrations_as_object": "true", "include_uid": "true", "include_timestamp": "true", "include_original_ep": "true"
    }
  }
}'
Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json
Request body
webhook Webhook (required)
Body Parameter — A JSON object that contains the optional headers and URL where notifications are sent.
Responses
status description schema
204 Successfully subscribed.
400 Given URL is not accessible, or other type of channel already exists.
401 Unauthorized.
403 Forbidden. The authorization token used is not an API key.
415 Unsupported Media Type.
put /v2/notification/websocket
(PREVIEW) Register a websocket channel. Show more Show less

(PREVIEW) Register (or update) a channel using websocket connection to deliver notifications. The websocket channel should be opened by client using /v2/notification/websocket-connect endpoint. To get notifications pushed, you must place subscriptions. For more information on notification messages, see NotificationMessage.

A websocket channel can have only one active websocket connection at a time. If a websocket connection for a channel exists and a new connection to the same channel is made, the connection is accepted and the older connection is closed.

Expiration of a websocket:

A websocket channel is expired if the channel does not have an opened websocket connection for a 24-hour period. Channel expiration means the channel is deleted and any undelivered notifications stored in its internal queue is removed. As long as the channel has an opened websocket connection or time between successive websocket connections is less than 24 hours, the channel is considered active, notifications are stored in its internal queue and delivered when a websocket connection is active. A channel can be also deleted explicitly with a DELETE call.

More about notification sending logic.

Configuration options:

The event notification channel provides configurations options defined in Serialization config

Example:

curl -X PUT https://api.us-east-1.mbedcloud.com/v2/notification/websocket \
-H 'Authorization: Bearer <api_key>'
-d '{
  "serialization": {"type": "v2", "max_chunk_size": "100",
    "cfg": {"deregistrations_as_object": "true", "include_uid": "true", "include_timestamp": "true", "include_original_ep": "true"
    }
  }
}
Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json
Return type
Example data
Content-Type: application/json
{
  "serialization" : "{}"
}
Responses
status description schema
200 Channel successfully updated. In the current v2 implementation this operation has no effect, and any subsequent PUT call from a client previously registered to a channel results in a 200 OK response. RegisterWebsocketChannel
201 Channel succesfully registered. WebsocketChannel
400 Other type of channel already exists.
401 Unauthorized.
403 Forbidden. The authorization token used is not an API key.

Resources

delete /v2/endpoints/{device-id}/{resourcePath}
(DEPRECATED) Delete a resource path. Show more Show less
Deprecation Date:
Expected End of Life:
/v2/endpoints/{device-id}/{resourcePath} is replaced by /v2/device-requests/{device-id}.
Links:

(DEPRECATED) A request to delete a resource path must be handled by both Device Management Client and Device Management Connect.

All resource APIs are asynchronous. These APIs respond only if the device is on and connected to Device Management Connect, and there is an active notification channel.

Example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v2/endpoints/{device-id}/{resourcePath} \
-H 'Authorization: Bearer <api_key>'
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. The ID must be an exact match. Do not use wildcards.
resourcePath (required)
Path Parameter — The resource URL.
Query parameters
noResp (optional)
Query Parameter

If you make a request with noResp=true, Device Management Connect makes a CoAP non-confirmable request to the device. Such requests are not guaranteed to arrive at the device, and do not return an async-response-id.

If calls with this parameter enabled succeed, they return with the status code 204 No Content. If the underlying protocol does not support non-confirmable requests, or if the endpoint is registered in queue mode, the response is status code 409 Conflict.

Return type
Example data
Content-Type: application/json
{
  "async-response-id" : "9e3c96b8-c4d7-496a-ab90-cc732b9b560e"
}
Responses
status description schema
202 Accepted. Returns an asynchronous response ID. AsyncID
400 Bad request.
404 Requested endpoint’s resource is not found.
409 Conflict. If noResp=true, the non-confirmable request is not supported by the used protocol.
410 Gone. Endpoint not found.
429 Cannot accept the request at the moment: the queue is full.
502 TCP or TLS connection to endpoint cannot be established.
post /v2/endpoints/{device-id}/{resourcePath}
(DEPRECATED) Execute a function on a Resource or create new Object instance. Show more Show less
Deprecation Date:
Expected End of Life:
/v2/endpoints/{device-id}/{resourcePath} is replaced by /v2/device-requests/{device-id}.
Links:

(DEPRECATED) Execute a function on an existing resource and create a new Object instance on the device. The resource path does not have to exist; you can set it with the call. The maximum length of the resource path is 255 characters.

All resource APIs are asynchronous. These APIs respond only if the device is on and connected to Device Management Connect, and there is an active notification channel.

Supported content types depend on the device and its resource. Device Management translates HTTP to the equivalent CoAP content type.

Example:

This example resets the min and max values of the temperature sensor instance 0 by executing Resource 5605 'Reset Min and Max Measured Values'.

curl -X POST https://api.us-east-1.mbedcloud.com/v2/endpoints/{device-id}/3303/0/5605 \
-H 'Authorization: Bearer <api_key>'
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. The ID must be an exact match. Do not use wildcards.
resourcePath (required)
Path Parameter — The resource URL.
Consumes
This API call consumes the following media types via the Content-Type request header:
  • text/plain
  • application/xml
  • application/octet-stream
  • application/exi
  • application/json
  • application/link-format
  • application/senml+json
  • application/nanoservice-tlv
  • application/vnd.oma.lwm2m+text
  • application/vnd.oma.lwm2m+opaq
  • application/vnd.oma.lwm2m+tlv
  • application/vnd.oma.lwm2m+json
Request body
resourceFunction string (optional)
Body Parameter — This value is not needed. Most of the time, resources do not accept a function but they have their own functions predefined. You can use this to trigger them. If a function is included, the body of this request is passed as a char* to the function in Device Management Client.
Query parameters
noResp (optional)
Query Parameter

If you make a request with noResp=true, Device Management Connect makes a CoAP non-confirmable request to the device. Such requests are not guaranteed to arrive in the device, and you do not get back an async-response-id.

If calls with this parameter enabled succeed, they return with the status code 204 No Content. If the underlying protocol does not support non-confirmable requests, or if the endpoint is registered in queue mode, the response is status code 409 Conflict.

Return type
Example data
Content-Type: application/json
{
  "async-response-id" : "9e3c96b8-c4d7-496a-ab90-cc732b9b560e"
}
Responses
status description schema
202 Accepted. Returns an asynchronous response ID. AsyncID
400 Bad request.
404 Requested endpoint’s resource not found.
409 Conflict. If noResp=true, the non-confirmable request is not supported by the used protocol.
410 Gone. Endpoint not found.
429 Cannot accept the request at the moment: the queue is full.
502 TCP or TLS connection to endpoint cannot be established.
get /v2/endpoints/{device-id}/{resourcePath}
(DEPRECATED) Read from a resource. Show more Show less
Deprecation Date:
Expected End of Life:
/v2/endpoints/{device-id}/{resourcePath} is replaced by /v2/device-requests/{device-id}. The /v2/device-requests/{device-id} endpoint lets you use your own async-id, and simplifies integration by returning all resource values, cached and non-cached, through the event notification channel.
Links:

(DEPRECATED) Requests the resource value either from the device or cache. If the value is not in the cache, the request goes all the way to the device. When the response is available, an AsyncIDResponse JSON object is received in the notification channel. The resource values can be also in cache based on max_age defined by the device side. The value found from the cache is returned immediately in the response.

The preferred way to get resource values is to use the subscribe and callback methods.

All resource APIs are asynchronous. These APIs only respond if the device is on and connected to Device Management.

See also how resource caching works.

Please refer to Lightweight Machine to Machine Technical specification for more inforamtion.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/endpoints/{device-id}/{resourcePath} \
-H 'Authorization: Bearer <api_key>'
Path parameters
device-id (required)
Path Parameter — Unique Device Management device ID for the endpoint. The ID must be an exact match. Do not use wildcards.
resourcePath (required)
Path Parameter — The resource URL.
Query parameters
cacheOnly (optional)
Query Parameter — If true, the response comes only from the cache. Default: false. Device Management Connect caches the received resource values for the time of max_age defined in the client side.
noResp (optional)
Query Parameter

If a request is made with noResp=true, Device Management Connect makes a CoAP non-confirmable request to the device. Such requests are not guaranteed to arrive on the device, and no async-response-id returns.

Successful calls return with the status code 204 No Content. If the underlying protocol does not support non-confirmable requests, or if the endpoint is registered in queue mode, the response is status code 409 Conflict.

Responses
status description schema
200 Resource value found in cache. Returns the string value of the resource.
202 Accepted. Returns an asynchronous response ID. AsyncID
205 No cache available for resource.
400 Bad request.
404 Requested endpoint’s resource is not found.
409 Conflict. If noResp=true, the non-confirmable request is not supported by the used protocol.
410 Gone. Endpoint not found.
429 Cannot accept the request at the moment: the queue is full.
502 TCP or TLS connection to endpoint cannot be established.
put /v2/endpoints/{device-id}/{resourcePath}
(DEPRECATED) Write to a Resource or use write-attributes (notification rules) for a Resource. Show more Show less
Deprecation Date:
Expected End of Life:
/v2/endpoints/{device-id}/{resourcePath} is replaced by /v2/device-requests/{device-id}.
Links:

(DEPRECATED) With this API, you can write a new value to existing Resources or use the write attribute to set notification rules for the Resources. The notification rules only work on the device client side and may not be supported by all clients.

This API can also be used to transfer files to the device. Device Management Connect LwM2M server implements Option 1 from RFC7959. The maximum block size is 1024 bytes. Note block size versus transferred file size in low-quality networks. The customer application needs to know what type of file is transferred (for example, TXT) and the customer can encrypt the payload. The maximum payload size is 1048576 bytes.

All resource APIs are asynchronous. These APIs respond only if the device is on and connected to Device Management Connect, and there is an active notification channel.

Supported content types depend on the device and its resource. Device Management translates HTTP to equivalent CoAP content type.

Example:

This example sets the alarm on a buzzer. The command writes the Buzzer instance 0, "On/Off" boolean resource to '1'.

curl -X PUT https://api.us-east-1.mbedcloud.com/v2/endpoints/{device-id}/3338/0/5850 \
-H "content-type: text/plain" \
-H 'Authorization: Bearer <api_key>' \
-d '1'
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. The ID must be an exact match. Do not use wildcards.
resourcePath (required)
Path Parameter — Resource URL.
Consumes
This API call consumes the following media types via the Content-Type request header:
  • text/plain
  • application/xml
  • application/octet-stream
  • application/exi
  • application/json
  • application/link-format
  • application/senml+json
  • application/nanoservice-tlv
  • application/vnd.oma.lwm2m+text
  • application/vnd.oma.lwm2m+opaq
  • application/vnd.oma.lwm2m+tlv
  • application/vnd.oma.lwm2m+json
Request body
resourceValue string (required)
Body Parameter — The value to set to the resource.
Query parameters
noResp (optional)
Query Parameter

If you make a request with noResp=true, Device Management Connect makes a CoAP non-confirmable request to the device. Such requests are not guaranteed to arrive to the device, and do not return an async_response_id.

If a call with this parameter enabled succeeds, it return status code 204 No Content. If the underlying protocol does not support non-confirmable requests, or if the endpoint is registered in queue mode, the response is status code 409 Conflict.

Return type
Example data
Content-Type: application/json
{
  "async-response-id" : "9e3c96b8-c4d7-496a-ab90-cc732b9b560e"
}
Responses
status description schema
202 Accepted. Returns an asynchronous response ID. AsyncID
400 Bad request.
409 'Conflict. If noResp=true, the non-confirmable request is not supported by the used protocol.'
410 Gone. Endpoint not found.
429 Cannot accept the request at the moment: the queue is full.
502 TCP or TLS connection to endpoint cannot be established.

Subscriptions

put /v2/subscriptions/{device-id}/{resourcePath}
Subscribe to a resource path. Show more Show less

The Device Management Connect eventing model consists of observable Resources.

This means that endpoints can deliver updated resource content, periodically or with a more sophisticated solution-dependent logic. The OMA LwM2M resource model also supports including objects, object instances, resources, and resource instances.

Applications can subscribe to objects, object instances or individual resources to make the device provide value change notifications to Device Management Connect service. An application needs to call a /notification/callback method to get Device Management Connect to push notifications of the resource changes.

Notification rules

A web application can place dynamic observation rules for individual Object Instances and Resources to define when the device sends observations. More information in Notification rules.

All manual subscriptions are removed during a full device registration, at which point applications must re-subscribe. To avoid this, you can use /subscriptions to set a pre-subscription.

Example:

curl -X PUT https://api.us-east-1.mbedcloud.com/v2/subscriptions/{device-id}/{resourcePath} \
-H 'Authorization: Bearer <api_key>'
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. The ID must be an exact match. Do not use wildcards.
resourcePath (required)
Path Parameter — The resource URL.
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Successfully subscribed.
202 Accepted. Returns an asynchronous response ID used to reference the future asynchronous response. AsyncID
400 Bad request, malformed content.
404 Endpoint or its resource not found.
429 Cannot accept the request at the moment: the queue is full.
502 Subscription failed: endpoint not connected.
get /v2/subscriptions/{device-id}/{resourcePath}
Read subscription status Show more Show less
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. The ID must be an exact match. Do not use wildcards.
resourcePath (required)
Path Parameter — The resource URL.
Responses
status description schema
200 Resource is subscribed.
404 Resource is not subscribed.
delete /v2/subscriptions/{device-id}
Delete subscriptions from an endpoint. Show more Show less

Deletes all resource subscriptions in a single endpoint.

Example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v2/subscriptions/{device-id} \
-H 'Authorization: Bearer <api_key>'
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. The ID must be an exact match. Do not use wildcards.
Responses
status description schema
204 Successfully removed.
delete /v2/subscriptions
Remove pre-subscriptions. Show more Show less

Removes pre-subscriptions.

Example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v2/subscriptions \
-H 'Authorization: Bearer <api_key>'
Responses
status description schema
204 Successfully removed subscriptions.
401 Unauthorized.
403 Forbidden: the authorization token used is not an API key.
delete /v2/subscriptions/{device-id}/{resourcePath}
Remove a subscription. Show more Show less

Remove an existing subscription from a resource path.

Example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v2/subscriptions/{device-id}/{resourcePath} \
-H 'Authorization: Bearer <api_key>'
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. The ID must be an exact match. Do not use wildcards.
resourcePath (required)
Path Parameter — The resource URL.
Responses
status description schema
204 Successfully removed subscription.
404 Endpoint or resource not found.
get /v2/subscriptions/{device-id}
Read endpoints subscriptions Show more Show less

Lists all subscribed resources from a single endpoint.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/subscriptions/{device-id} \
-H 'Authorization: Bearer <api_key>'
Path parameters
device-id (required)
Path Parameter — A unique Device Management device ID for the endpoint. The ID must be an exact match. Do not use wildcards.
Return type
String
Example data
Content-Type:
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • text/uri-list
Responses
status description schema
200 List of subscribed resources. String
404 Endpoint not found, or there are no subscriptions for that endpoint.
get /v2/subscriptions
Get pre-subscriptions. Show more Show less

Retrieve pre-subscription data. The server returns a JSON structure. If there are no pre-subscribed resources, it returns an empty array.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/subscriptions \
-H 'Authorization: Bearer <api_key>'
Return type
Example data
Content-Type: application/json
""
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 OK. PresubscriptionArray
401 Unauthorized.
403 Forbidden: the authorization token used is not an API key.
put /v2/subscriptions
Set pre-subscriptions Show more Show less

Pre-subscription is a set of rules and patterns established by the application. When an endpoint registers and its ID, type, and registered resources match the pre-subscription data, Device Management Connect automatically sends subscription requests to the device. The pattern may include the endpoint ID (optionally having an * character at the end), endpoint type, a list of resources, or expressions with an * character at the end. Subscriptions based on pre-subscriptions are done when device registers or does register update. To remove the pre-subscription data, put an empty array as a rule.

Notification rules

A web application can place dynamic observation rules for individual Object Instances and Resources to define when the device sends observations. More information in Notification rules.

Limits:

  • The maximum length of the endpoint name and endpoint type is 64 characters.
  • The maximum length of the resource path is 128 characters.
  • You can listen to 256 separate resource paths.
  • The maximum number of pre-subscription entries is 1024.

Example request:

curl -X PUT https://api.us-east-1.mbedcloud.com/v2/subscriptions \
-H 'Authorization: Bearer <api_key>' \
-H 'content-type: application/json' \
-d '[
       {
         "endpoint-name": "node-001",
         "resource-path": ["/dev"]
       },
       {
         "endpoint-type": "Light",
         "resource-path": ["/sen/*"]
       },
       {
         "endpoint-name": "node*"
       },
       {
         "endpoint-type": "Sensor"
       },
       {
         "resource-path": ["/dev/temp","/dev/hum"]
       }
    ]'
  • Subscribe to /dev resource of endpoint named node-001.
  • Subscribe to Light type of endpoints and their resources prefixed with /sen/.
  • Subscribe to all observable resources of endpoint names prefixed with node.
  • Subscribe to all observable resources of Sensor type endpoints.
  • Subscribe to /dev/temp and /dev/hum resources of all endpoints.

Note: For efficiency, you should use resource path patterns in the pre-subscription data. This prevents notification flow from unwanted resources.

Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json
Request body
presubsription PresubscriptionArray (required)
Body Parameter — Array of pre-subscriptions.
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • text/plain
Responses
status description schema
204 Successfully created.
400 Bad request, malformed content.
401 Unauthorized.
403 Forbidden: the authorization token used is not an API key.

Models

AsyncID

async-response-id (optional)
String

Asynchronous response unique ID.

AsyncIDResponse

id (optional)
String

The unique ID of the asynchronous response.

status (optional)
Integer

States whether sending a command to the device succeeded or failed.

Code Description
200 Operation succeeded. The playload contains result of the operation from the device.
404 Endpoint does not have requested resource.
412 Precondition failed and operation was not executed. Device responded with 4.12 CoAP response code.
413 Request entity is too large and could not be delivered to the device.
415 Endpoint does not support media type.
429 Expired request was removed from queue (REQUEST_EXPIRED), device requested deregistration (DEVICE_REMOVED_REGISTRATION), or device was suspended (DEVICE_BLOCKED).
502 Request to the device failed and retry count exceeded. Last retry failed to establish TCP or TLS connection to endpoint.
503 Request to the device failed and retry count exceeded. Last retry failed because endpoint is currently unavailable (NOT_CONNECTED).
504 Request to the device failed and retry count exceeded. Last retry failed, as device did not respond in the time of protocol-specific retransmission logic (TIMEOUT).

error (optional)
String

An optional error message describing the error. Please refer to status listing above.

payload (optional)
String

Requested data, base64 encoded.

ct (optional)
String

The content type.

max-age (optional)
String

Determines how long this value stays valid in the cache, in seconds. 0 means that the value is not stored in the cache.

ChannelMetadata

delivery_mechanism (optional)
String

Channel delivery mechanism.

Enum:
CALLBACK
LONG_POLLING
WEB_SOCKET

DeviceRequest

method
String

The CoAP request method. Allowed values are GET, POST, PUT and DELETE.

uri
String

The URI path of the requested resource.

accept (optional)
String

The content type of an accepted response.

content-type (optional)
String

The content type of the payload.

payload-b64 (optional)
String

The base64 encoded payload to send to the device.

EndpointData

ep (optional)
String

Unique Device Management device ID.

original-ep (optional)
String

If device registration is initiated with a self-provided endpoint name, Device Management provides a new device ID for subsequent use. The new platform-provided Device ID is forwarded as the 'ep' property and the original self-provided one as the optional 'original-ep' property in a registration notification. The name and ID can then be mapped accordingly. Device Management saves the original endpoint name in the Device Directory for future device registrations so you don't need to do mapping again.

ept (optional)
String

Endpoint type.

q (optional)
Boolean

Queue mode (default value is false).

resources (optional)

NotificationData

ep (optional)
String

Device Management Device ID.

path (optional)
String

URI path.

ct (optional)
String

Content type.

payload (optional)
String

Base64 encoded payload.

max-age (optional)
String

Max age value is an integer number of seconds between 0 and 2^32-1, but the actual maximum cache time is limited to 3 days. Default 60.

NotificationMessage

notifications (optional)
registrations (optional)
reg-updates (optional)
de-registrations (optional)
registrations-expired (optional)
async-responses (optional)

Presubscription

endpoint-name (optional)
String

The device ID.

endpoint-type (optional)
resource-path (optional)

PresubscriptionArray

RegisterWebsocketChannel

serialization (optional)
Object

Serialization configuration for a channel

Resource

uri
String

The resource URL.

rt (optional)
String

Application-specific resource type that describes this resource. It is created by the client side application. Not meant to be a human-readable name for the resource. Multiple resource types may be included, separated by a space.

obs (optional)
Boolean

'Determines whether you can subscribe to changes for this resource. It can have values true or false.'

type (optional)
String

The content type of the resource.

We recommend you use the resource types listed in the LwM2M specification.

ResourcePath

A resource URI.

ResourcesData

path (optional)
String

Resource's URI path.

if (optional)
String

Interface description that defines a name or URI that indicates how to interact with the target resource. It describes a generic interface type, such as a 'sensor'.

rt (optional)
String

Application-specific resource type that describes this resource. It is created by the client side application. Not meant to be a human-readable name for the resource. Multiple resource types may be included, separated by a space.

ct (optional)
String

Content type.

obs (optional)
Boolean

Whether the resource is observable (true/false).

SerializationConfigData

type
String

Serialization type: v2 - specified in NotificationMessage.

Enum:
v2
max_chunk_size (optional)
Integer

Maximum number of messages in NotificationMessage container delivered in one request. Default is 10000. Using a very low value for high troughput applications may cause lag in notification delivery, as a new chunk is sent only after the previous one has been acknowledged. Using a high value is recommended and safe, as chunks are sent quickly after notifications are received from devices. See notification sending logic for more details.

cfg (optional)
Object

Serialization configuration object according to configuration type.

SerializationConfigObjectV2

deregistrations_as_object (optional)
Boolean

Defines serialization format for 'de-registrations' and 'registrations-expired'. If set to true, de-registration and registration-expired messages will be represented as json objects and can have additional fields: 'uid', 'timestamp', 'original-ep', together with the 'ep' field. If set to false, (default) - de-registration and 'registration-expired' will be represented by a string, containing only data from 'ep' field.

include_uid (optional)
Boolean

Include 'uid' message field to serialized objects. This is message ID, and can be used for duplicate detection.

include_timestamp (optional)
Boolean

Include 'timestamp' message field in serialized objects. The timestamp represents the time that the notification service receives the message and sorts it into the queue. Timestamp provides information of queue length (web-app current time - timestamp = delay).

include_original_ep (optional)
Boolean

Include 'original-ep' message field in serialized objects. This is the endpoint_name from the device.

SubscriptionsList

A list of resource URIs, one per line.

Webhook

url
String

The URL to which the notifications are sent. We recommend that you serve this URL over HTTPS.

headers (optional)
map[String, String]

The headers (key/value) sent with the notification. Optional.

serialization (optional)
Object

Serialization configuration for a channel.

WebsocketChannel

status (optional)
String

Channel status is 'connected' when the channel has an active WebSocket bound to it. The state is 'disconnected' when either the channel or the WebSocket bound to it is closed.

Enum:
connected
disconnected
queue_size (optional)
Integer

Number of events in the channel's event queue waiting to be delivered.

serialization (optional)
Object

Serialization configuration for a channel.