# Device API
Device API is responsible for processing requests from device and sending back notifications and acknowledgements. Device API is also responsible for propagating to device cloud originating subscribed model changes (platform events) back to device.
Currently, the Platform supports two versions of the API: V1 and V2. V1 is an older version and it is to be deprecated in one of the future releases of the platform. It is therefore recommended that your devices use the Device API V2.
NOTE
Ability Edge support for Device API v2 messages is planned for a future release. Currently, it uses Device API v1 for its operations.
TIP
To see practical example of using the Device API,look at the Codebits project.
# Requests - device to cloud (D2C)
Device originated requests that Device API must listen to. Each event of this type must be validated to ensure that the device requesting/updating this model has the right to do so.
D2C message size limit is 256 kB (including headers).
# Device API V1 Requests
See rules under each specific request type below:
# Device API V2 Requests
See rules under each specific request type below:
# Device API V1 Responses (C2D)
There are following responses to each Device API V1 request, sent as C2D messages back to device:
- 'request-response' notifications - described in specific request subpage
- Abb.Ability.InformationModel.ObjectModelCreated
- Abb.Ability.InformationModel.ObjectModelUpdated
- Abb.Ability.InformationModel.ObjectModelDeleted
- 'publish-subscribe' notifications - described in specific request subpage
- Abb.Ability.InformationModel.ObjectModelCreated
- Abb.Ability.InformationModel.ObjectModelUpdated
- see Subscriptions & Notification Types for details about notification types
- acknowledgements - see Acknowledgement Handling.
# DeviceApi V2 Responses (C2D)
There are following responses to each Device API V2 request, sent as C2D messages back to device:
- 'request-response' notifications - described in specific request subpage
- Abb.Ability.ObjectModel.Updated
- Abb.Ability.ObjectModel.Reference.Updated
- 'publish-subscribe' notifications - described in specific request subpage
- Abb.Ability.ObjectModel.Created
- Abb.Ability.ObjectModel.Updated
- see Subscriptions & Notification Types for details about notification types
- acknowledgements - see Acknowledgement Handling.
# Notifications for subscription changes (C2D)
'publish-subscribe' notifications can also be propagated to device when the subscribed object model has been changed directly via cloud API, such notification is not tied to any Device API request.
TIP
At this point in time, Device API is only responsible for proxying created/updated/deleted events for 'abb.ability.configuration' model definitions.
TIP
All such notifications are always sent in Device API V1 format. This may change in future release
See Subscriptions & Notification Types for details about notification types.
# C2D Message TTL(Time To Live)
C2D TTL on Service Bus is 60 days. It is not refreshed by reschedules. Reschedules are performed until the message expires.
C2D message size limit is 64 kB (including headers).
# Device API Requests V2
The updated version of the Device API events greatly expands the available requests you are able to make to the Ability Platform IoT Hub. Each event message is detailed on its own individual page where you will find specific information about structuring the request and what the typical response looks like. Each event has a set of common headers added required by the Ability Platform and added by the IoT hub which you can review below. It is also now possible to batch events together in the v2 Device API. Please explore the new messages and details for use.
# Idempotency
All requests are idempotent, meaning that sending several identical requests will result in the same response being sent back for each request pending the action was successful. Additionally, idempotency implies that the state of the platform stays unchanged if the same message gets sent repeatedly.
NOTE The only exception from the idempotent behaviour is the model.create message, which may not be idempotent in some cases.
# Common Properties For All V2 Requests
# Ability Message Headers
All v2 messages for the Ability Platform will share these common message properties in the request. These need to be included in any Device API V2 message that your device sends.
| Property | Mandatory | Description |
|---|---|---|
| msgType | Mandatory | Must be equal to 'action' |
| action | Mandatory | Must be equal to 'identity.create' |
| version | Mandatory | Must be equal to 2 |
| correlationId | Optional | Correlation id Should be included to track correlation of platform components If not present, DCS will generate a new one |
| ack | Optional | Initialized to 'none' value if value missing Indicates an additional acknowledgement message to be sent to device For more details see Acknowledgement Handling |
| target | Optional | Represents target recipient for the ack/response messages. It consists of names of connected devices (principals) separated by a forward slash, that have to be registered identities. If present and principals are valid, it is guaranteed to be passed to all c2d messages generated as an outcome of this action. If not provided, defaults to empty string. |
| context | Optional | Context identifier, if present, it is guaranteed to be passed to all C2D messages generated as an outcome of this action. |
| content-type | Optional | Defines the format of the content of the message. Set according to IANA standard. Default is "application/json". Allowed values: "application/json" |
| content-encoding | Optional | Defines the encoding of the message, which also includes compression. Default is "utf-8". Allowed values: "utf-8", "gzip", or "deflate" You can read more about it here |
# Added by the IoT Hub
| Property | Mandatory | Description |
|---|---|---|
| iothub-connection-device-id | Mandatory | Device ID of the directly connected device. It may be any string. |
Each v2 message may have unique properties associated with its message that may be required to be included in your request. Those special cases are laid out below in the details of this article.
Headers size limit
There is a validation that checks the size of all header properties - size must not exceed 32 kB! If header size is too large, unsuccessful acknowledgement should be sent back with error code "platform_event_validation_error" and details "Request message header properties size limit of 32 kB exceed"
# Context property
The context property is an optional field that may be used by device
implementation if it needs to retain some information between the request and
the response (acknowledgement). The concept is the same as with the "state"
property in Microsoft Identity OAuth2
requests.
Contents of the context property will be passed as is (without any changes) in
all acknowledgements and request-response notifications.
Detailed list where it may be passed is below:
| Device API action | Responding C2D Message |
|---|---|
| identity.create identity.update identity.delete model.update model.patch model.delete owner.remove reference.create reference.delete extension.create extension.get type.create type.delete subscription.create encryptionKey.get | Acknowledgemt (no other responses are tied to this request) |
| model.create | Acknowledgement only Note: request-response notification for device model is no longer sent, publish-subscribe notification for configuration model is not affected |
| model.query | Acknowledgement and all queried models (which are request-response notifications) |
| type.query | All acknowledgements |
| subscription.create | Acknowledgement only Note: Any platform events triggered by subscription are propagated as publish-subscribe notifications and are not affected |
| batch.execute | Acknowledgement. For details see chapter "Context header in Batch messages" below |
Batch.Execute messages
For information on how to use context in batch messages, go to Batch.Execute (V2).
# Error handling
If a response can be delivered back to device, acknowledgments are sent back to device if they have been requested in the solution configuration. More details can be found here: Acknowledgement Handling.
All of the errors that may be returned are covered in Platform Error Responses.
# Batch Messages
Device API V2 messages can be batched when following the guidelines for properly batched messages being sent from a device to the cloud. Please find the details of batch messaging in its own article).