api-sig/guidelines
Monty Taylor 31f6575ce4 Add guidelines on Version Discovery
As an expansion of the guidelines around microversions, add guidelines
around how services should expose Version Discovery documents. This
includes recommendations for putting unversioned endpoints into the
catalog.

It also includes a completely new thought, so feel free to punch me in
the head - that versioned discovery documents should include a
collections rel link to allow clients to get from the versioned to the
universioned document without having to do URL manipulation. If we can
get that in, it should serve as a bridge for those clouds that are still
putting versioned endpoints into the catalog for a while for backwards
compat reasons.

Two related follow-up patches are in-work. One that adds a copy of the
consuming-discovery document with all of the extra effort in support of
clouds and services that to not implement these guidelines removed, so a
"perfect future state" is easy to read. The other is a document
recommending a global cloud "profile" that greatly reduces the API
burden on clients consuming this information.

Change-Id: Id8160048dfffc1ada32ce876a65b02fb7a02306e
2020-06-02 13:29:09 -05:00
..
consuming-catalog Add guidelines on Version Discovery 2020-06-02 13:29:09 -05:00
http Add guidance on needing cache-control headers 2018-04-12 21:47:22 +01:00
api-docs.rst Fix wrong openstack review link . 2019-11-20 10:15:20 +08:00
api_interoperability.rst Change API-WG to API-SIG 2017-10-12 18:07:33 +00:00
compatibility.rst Update compatibility doc and references 2017-07-26 17:20:31 +01:00
consuming-catalog.rst Add document describing consuming version discovery 2020-06-02 13:23:43 -05:00
counting.rst Fix typos in counting.rst 2016-03-21 19:19:28 +00:00
discoverability.rst Add guidelines on Version Discovery 2020-06-02 13:29:09 -05:00
dns-sd.rst Use doc8 to verify rst instead of custom tests 2020-03-19 11:43:16 +01:00
errors-example.json Expand schema for error.codes to reflect reality 2018-07-06 16:44:41 +01:00
errors-schema.json Expand schema for error.codes to reflect reality 2018-07-06 16:44:41 +01:00
errors.rst Merge "Add links to errors-example.json" 2018-07-26 16:28:50 +00:00
etags.rst Description of how to use etags to avoid lost updates 2016-04-12 12:30:11 +01:00
evaluating_api_changes.rst Create a set of api interoperability guidelines 2017-04-27 17:20:46 +01:00
extensions.rst Explain, simply, why extensions are bad 2017-09-07 16:35:55 +00:00
general.rst Add a "general" section 2015-01-06 14:27:59 +00:00
headers.rst Reword the note following microversion headers 2016-05-19 16:08:55 +00:00
http.rst Break up the HTTP guideline into smaller documents 2018-04-05 15:38:28 +02:00
links.rst A guideline for links 2016-08-25 11:55:59 -05:00
metadata.rst Delete multiple metadata items with a single request 2016-04-05 18:12:10 +03:00
microversion-errors-example.json Add version discover guideline for API microversions 2016-03-14 14:58:08 +08:00
microversion_specification.rst Add guidelines on Version Discovery 2020-06-02 13:29:09 -05:00
naming.rst Merge "Add guidelines for boolean names" 2017-02-16 16:38:06 +00:00
pagination_filter_sort.rst Update the URL in doc 2018-09-23 23:18:24 +08:00
representation_structure.rst Guideline for collection resources' representation structures 2014-12-11 10:51:32 +05:30
sdk-exposing-microversions.rst Add guideline on exposing microversions in SDKs 2018-03-15 15:55:54 +01:00
tags.rst Recommend the correct HTTP method for tags 2017-04-04 13:13:45 +00:00
terms.rst Add the condition for using a project term 2016-01-12 23:48:28 +00:00
testing.rst fix some errors for ill-syntax in testing.rst 2018-11-13 10:15:34 +08:00
time.rst Guidelines on using date and time format 2015-03-23 13:40:51 +02:00
uri.rst Fix missing close bracket 2017-06-28 18:34:18 +00:00
version-discovery-schema.json Add guidelines on Version Discovery 2020-06-02 13:29:09 -05:00
version-information-schema.json Add guidelines on Version Discovery 2020-06-02 13:29:09 -05:00
versioned-discovery-schema.json Add guidelines on Version Discovery 2020-06-02 13:29:09 -05:00