e809580088
The next patch actually describes desired state of version discovery. But in an epic amount of cart-before-the-horse, we have the process for consuming the discovery already because the process must take in to account the present as well as the past. This process has kept in mind what consuming the recommended discovery process _wants_ to look like in the future and in calls that out in a few places. The intent would be that the algorithm here would work for all clouds, but that as clouds and services adopt API-SIG recommendations, the interactions with the clouds would become more efficient. (so for clients using the complete algorithm they should be upwards compatible with forthcoming API-SIG guidelines and will just naturally do less work over time). I believe this is consistent in defaults, fallbacks and error conditions with what is currently implemented in keystoneauth, although there is additional logic presented here which is not yet in keystoneauth. The intent is for the process presented here to not change the behavior experienced by current keystoneauth users, with the exception that when the complete algorithm is implemented it's possible that an additional API call may be made on older clouds. That is to say, keystoneauth should not need to make any incompatible changes, but may need to add some features to be a fully compliant implementation. Apologies for the size and complexity. It turns out there are many historical oddities still lurking out there and advice to client authors that does not take them in to account would be incomplete. On the other hand, as we drive guidelines forward into being implemented, the need for this much crazy logic should go away. Co-Authored-By: Dmitry Tantsur <divius.inside@gmail.com> Change-Id: I241f76bca8ac27fc3d27028ae284b9012a2da7e9
506 B
506 B
API Discoverability
This topic document serves to provide guidance on how to have a public REST API expose the URIs and resources to end users in a machine-readable way.
See also the topic document on consuming-catalog.
See also the topic document on consuming-catalog/version-discovery.
Guidance
TODO Add sections that describe a best practice for API discoverability, possibly using JSON-Home, JSONSchema documents, and JSON-HAL.