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
Fix the Sphinx html_last_updated_fmt for Python3. The
html_last_updated_fmt option is interpreted as a byte
string in python3, causing Sphinx build to break.
This patch makes it utf-8 string.
Change-Id: I76f9c05023a30f434d2b873254ef0f63b31d86bf
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
Recent employment changes has resulted in several liasons no longer to
continue in that capacity. This patch updates with the current liaisons,
and also adds their emails, which will make contacting them about API-WG
issues simpler.
Change-Id: I22f37e462f2389b4ddc398d3d658c932d1b2e434
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
Include the name of the file that violates the unittest name check in
the error message so that it's easy to track down the problem. Also,
exclude emacs autosave files from the list.
Change-Id: Ib6a8557ee2bc2262fb0235c5641bd9da70f66fe0
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
When querying for supported versions, the example shows a single API,
with a `status` key that has a value of 'CURRENT'. This patch clarifies
the other possible status values, and what they mean to the consumer.
Closes-Bug: #1636641
Change-Id: I2e5450c77b6f614cff206c352d6d8a23b4f8e9a3
This is in response to the bug "Listing resources with invalid filters
should result in a 400", which caused problems in Keystone. We had a
similar guideline for handling invalid entries in a request body; this
adds similar guidance for query strings.
Change-Id: I92c1e0e25036c85398ffd0c40f9c16cb3e8a3029
Partial-Bug: #1654084
This patch adds guidelines for when to use the name 'state' vs. when to
use 'status'.
Closes-Bug: #1593313
Change-Id: Ie32387ae6330562fdf0ba4158017dcf2a73b0eef
The guideline on how to capitalize complex names uses the corresponding
style when mentioning the different styles to illustrate what each style
looks like. But the entry for 'MixedCase' is wrong. First, it is written
in CamelCase, but more importantly, "mixed case" refers to a variety of
styles of capitalization [0]. The only mixed case besides camelCase for
joined words is commonly called 'StUdLyCaPs' [1], in which the
capitalization is randomly altered.
[0] https://en.wikipedia.org/wiki/Capitalization
[1] https://en.wikipedia.org/wiki/Studly_caps
Change-Id: I41691bed53d5e30b445d042efbf6a7b5dce43185
There was some confusion of the appropriateness of using 400 when a
resource referenced in the body of a request did not exist. An example
of this is when creating a VM, but passing a non-existent flavor in the
request body. This patch clarifies that usage, and adds language to
emphasize that it is critical to be explicit as to exactly what is wrong
so that the issuer of the bad request knows exactly what must be done to
correct the problem.
Change-Id: Ie7b3f4cc49056380f31796aa4cebd99a574c132a
When filtering, one can use the ``in:`` operator to filter on results
that have a particular value in a specified list.
The question of how to specify a value that is *not* in a list came up,
so this patch adds the ``nin:`` operator to signify "not in". Note that
there was also a good deal of ambivalence between ``nin:`` and
``not_in:``, but it was felt that ``nin:`` was more consistent with
``neq:``.
Change-Id: I56049fccdea1d766fcccfd38307b02ef3baf7dd9
