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 is not documented
A booking has state behaviour, defined by the BookingStatus schema. This state behaviour should be documented, indicating how the booking will 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, it is not mentioned that only a single booking can be created for a given device, and additional bookings for that device will result in a 409 ALREADY_EXISTS error. This may not be obvious to a potential API consumer when first reading this documentation.
-
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 is not documented
A booking has state behaviour, defined by the
BookingStatusschema. This state behaviour should be documented, indicating how the booking will progress from one state to the nextError 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, it is not mentioned that only a single booking can be created for a given device, and additional bookings for that device will result in a
409 ALREADY_EXISTSerror. This may not be obvious to a potential API consumer when first reading this documentation.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