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
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
The recent yasfb is not compatible with ancient sphinx, just bump
both requirements, as well as replace deprecated oslosphinx with
openstackdocstheme (requirements shamelessly copied from ironic-specs).
While we're here, uncap pbr and bump it to 1.0.
Change-Id: Ia78499827a53f5ee0c7a8b0d9951a0e37dedc91b
Add '_' as a valid character in error.codes, because that's what's
present in the wild.
The schema is updated to include a pattern check, and one of the
examples is changed to demonstrate the use of the new char.
Change-Id: I6bcfd5d411b2b9c540546f92859647333114a8f8
They've been TODO for a long time. The provided links are
examples only, but include advice that services should publish
their own error code documentation.
Change-Id: I8e80160abc51ace34e8e286defc9ebe6a7847d54
Story: 1593321
Task: 22178
Based on conversation in IRC http://p.anticdent.org/282V , update
the errors guideline to be more specific about:
* using specific codes for specific cases
* adding errors is okay and not a breaking-change
Change-Id: I473918ce9c6b49c0b904e93b7140421525f4e7c0
This adds some practical guidance to the existing section on caching
to make it clear that where responses are not making explicit
assertions about controlling cache, they MUST "cache-control: no-cache"
Change-Id: If13a5a19ff077cd9a2c9c400c24af70ea6f818d9
Closes-Bug: #1747935
The current HTTP guideline is very, very large. It will be more easily
discovered and consumed by breaking it up into logical chunks.
Co-Authored-By: Dmitry Tantsur <dtantsur@redhat.com>
Change-Id: I964b1f31e50c93f59e5dc07d7643c6c21b51f762
Something must have changed somewhere in the docs jobs
which made an error show up in the gate where the header
in question had the wrong nesting.
Interestingly, this had apparently impacted the publishing
job, making it so the published page hasn't had the new
content. For months:
http://specs.openstack.org/openstack/api-wg/guidelines/pagination_filter_sort.html#filtering
Change-Id: Ifb86989f37425513f75558b2e15ab12460a7cc61
An alternate that is suggested for people who cannot add link sections
to the response body is the RFC 5988 Link header.
Move it to its own section for ease of linking, and change the text from
'can consider' to 'should'.
Also, add a note about API breakage and versioning related to adding
Link headers.
Change-Id: Ide4124513e3328084c53a2122384a4e25ea6c863
This updates as many references to 'API-WG', 'API Working Group', etc.,
to reflect the name change to the API-SIG.
Change-Id: I15ca0860c58bd7ba51f08dd39e551a774d7a060a
This tries to keep it as simple as possible and refrains from going into
history or examples, because it's not clear if any of that is relevant
beyond the interop concern.
Change-Id: Iae9f93ab73e17a626858641d2528f7a7c03c80b2
Closes-Bug: #1593331
Closes-Bug: #1593330
Closes-Bug: #1593328
In the consuming-catalog spec:
- Correct the URL pointing to the schema for service-types.json
- Minor typographical fixups
Change-Id: I4b5b81c64e55a16d05923da447d1c9544aea99b8
The compatibility doc was out of date and making promises of having
additional information that is now provided by the interoperability
document. So we now link from compatibility to api_interoperability and
in discoverability where we had been linking to compatibility we now
link to the recent information on consuming the catalog.
Change-Id: I296d5b167ffad63a256a2b133ee9250710e2837b
Closes-Bug: #1593312
This adds a "next_min_version" field in the versions body returned by
the root endpoint for a service using microversions. This gives a clear
signal to clients that the minimum supported microversion is going to
change. It also adds a "not_before" field that guarantees the that the
current minimum version will be supported up to that date, giving
consumers a sense of how quickly they need to update their programs.
Co-Authored-By: Ed Leafe <ed@leafe.com>
Change-Id: Ib717221ce6d162e3efca822a5a6b0a7ac689d7b0
The service-types-authority data is the canonical description of the
service type names and their aliases, but it needs to be consumable if
it's to be the basis of API consumption processes.
Describe how we publish the data so that consumers can depend on it.
Change-Id: I88a2fe2e20252f91a44bcfedbcff9e5acbe049bc
There are a few services that have widely used service-types that
do not match the current recommendation from the Service Types
Authority. The process for consuming service information from the
catalog is incomplete without taking those into account.
Change-Id: I30e1392a06531844e1247bbf3d616a24be934baa
Having gone all the way down the rabbit hole... there is nowhere that
actually describes how to select an endpoint from the catalog. This is
just a description of today and matches what keystoneauth is doing.
There are a couple of places where the process described isn't perfect.
For instance, at the end of endpoint selection we just pick the first
from the list if there are still multiple. While that's not _great_ -
it's keystoneauth's current behavior and changing it to be an error
condition would break many many things. So while an attempt has been
made to make this forward compatible with a completely sane future,
there are a few places where, for historical reasons, we need to keep a
non-optimal behavior. They're noted within.
Change-Id: Ie36e8802eff01a846dd6f0d73a5a656856f5ca7d
A new tag has been proposed in governance (see
I34cdfe0e00cd29d816e94668ace2146d66734814 ) which asserts that a
project follows OpenStack guidelines for an API maintaining
compatibility over time. The original "Evaluating API Changes"
guideline is used as the reference for what compatibility means.
That guideline was copied from the wiki in May 2015 and the content
that had been on the wiki last saw substantive change in August of
2012[1]. Under review it was discovered the guidance insufficiently
robust in a situation where the primary goal is for there to be
interoperability between clouds.
A new set of guidelines on what signifies change or instability in an API
is created in this document, with a new name, and with greater context on
the reasoning. The old document has been updated to link to this new
one with an explanation for why.
[1] https://wiki.openstack.org/w/index.php?title=APIChangeGuidelines&action=history
Change-Id: I0063c892cb1bddcca0745cd9f16b5004ff57959a
Co-Authored-By: Ron De Rose <ronald.de.rose@intel.com>
Co-Authored-By: Ian Cordasco <graffatcolmingov@gmail.com>
Change-Id: I0daac580155e98555a3775de4cb3923d519df503
The example does not exactly match what is returned by nova (which
does not use max_version) so remove the statement asserting that it
does.
Change-Id: I76475263ed495f7ca367c8b29b0872073c1846e3
The existing guideline recommends to do a GET on a tag to check its
existence, while our HTTP guideline recommends HEAD for such checks.
Since this is just a check, we should recommend HEAD in this case.
Wording was also added to the HTTP guideline stating that in all cases
where HEAD is implemented, the corresponding GET must be implemented,
too.
Closes-Bug #1677360
Change-Id: I36045e84e906dfbdf60c8989e2a5a5fb39b7cc34
http.rst contains "HAS BODY?", but it is not so clear that it means
a request body or a response body. On the bug report 1677360, we said
HEAD can be used as low-cost version of GET by none response body.
On the table, both of HEAD and GET is NO on "HAS BODY?". So the column
means a request body. This patch makes the meaning clear.
Change-Id: Idbfc6185ffe33774ce89a591cb034288e0953a36
Related-Bug: #1677360
Monty Taylor