Problem description
The info.description section needs to be updated to clarify API operation of the API and fix documentation errors:
-
Lifecycle of a booking and assignment is not documented
Bookings and assignments have state behaviour, which should be summarised in the info.description section. Explain the defined status values - "PENDING" "SUCCESSFUL" "PARTIAL_SUCCESS" "FAILURE" - for each operation, and which of the statusInfo values are valid for each - "DEVICE_NOT_FOUND" "DEVICE_UNKNOWN_ERROR" "DEVICE_DISCLOSURE_POLICY_APPLIED" "QUOTA_EXCEEDED" "VALIDATION_PENDING" "ASSIGNMENT_COMPLETED" "BOOKING_INVALID" "BOOKING_CANCELLED" "BOOKING_EXPIRED" "BOOKING_TERMINATED" "RELEASE_PENDING".
Document how bookings and assignments progress from one state to the next.
-
Error behaviour should be more comprehensively summarised
A summary is given as to what might trigger some 400 or 422 error conditions, but many error codes and error conditions are not mentioned. For example, what conditions or restrictions would give rise to a 409 error which is, by definition, an API consumer input error.
-
Use case restrictions when using 3-legged access tokens needs to be summarised
It is explained that 3-legged access tokens are required to remain compliant with privacy regulations, but the limitations this places on the use case should be summarised somewhere in this section. In particular:
- Batch assignment and release of devices to/from a booking is not possible, and devices must be assigned/released individually
- The API does not return any identifier for a device that was identified using a 3-legged access token, so the API consumer is responsible to track which devices are assigned to a given booking. They can, however, discover which bookings a given device identified by a 3-legged access token has been assigned to.
-
Hard-coded API version number:
Note: Network Access Identifier is defined for future use and will not be supported with v0.1 of the API.
-
No blank line after SGML comments which causes rendering issues with Swagger-UI, e.g.:
<!-- CAMARA:MANDATORY:identifying-device-from-access-token:BEGIN -->
# Identifying the device from the access token
Expected action
Review documentation and update
Additional context
None
Problem description
The
info.descriptionsection needs to be updated to clarify API operation of the API and fix documentation errors:Lifecycle of a booking and assignment is not documented
Bookings and assignments have state behaviour, which should be summarised in the
info.descriptionsection. Explain the definedstatusvalues - "PENDING" "SUCCESSFUL" "PARTIAL_SUCCESS" "FAILURE" - for each operation, and which of thestatusInfovalues are valid for each - "DEVICE_NOT_FOUND" "DEVICE_UNKNOWN_ERROR" "DEVICE_DISCLOSURE_POLICY_APPLIED" "QUOTA_EXCEEDED" "VALIDATION_PENDING" "ASSIGNMENT_COMPLETED" "BOOKING_INVALID" "BOOKING_CANCELLED" "BOOKING_EXPIRED" "BOOKING_TERMINATED" "RELEASE_PENDING".Document how bookings and assignments progress from one state to the next.
Error behaviour should be more comprehensively summarised
A summary is given as to what might trigger some 400 or 422 error conditions, but many error codes and error conditions are not mentioned. For example, what conditions or restrictions would give rise to a 409 error which is, by definition, an API consumer input error.
Use case restrictions when using 3-legged access tokens needs to be summarised
It is explained that 3-legged access tokens are required to remain compliant with privacy regulations, but the limitations this places on the use case should be summarised somewhere in this section. In particular:
Hard-coded API version number:
No blank line after SGML comments which causes rendering issues with Swagger-UI, e.g.:
<!-- CAMARA:MANDATORY:identifying-device-from-access-token:BEGIN --># Identifying the device from the access tokenExpected action
Review documentation and update
Additional context
None