# 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. Additionally, have a look at this article to see some simpler examples.
# 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).