# 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).