* Update api-wg from branch 'master'
- Merge "Add guidance on needing cache-control headers"
- Add guidance on needing cache-control headers
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
* Update api-wg from branch 'master'
- Merge "Remove use of Python builtin name for variables"
- Remove use of Python builtin name for variables
'file' is a Python builtin name, and should not be used for a variable
name.
Fixes-Bug: #1763469
Change-Id: Ifb0a3fe51f995cee5d703be23ea444da3e837be6
* Update api-wg from branch 'master'
- Update the errors guidance to use service-type for code
Also, explain a bit about why errors exist and how the code
can be used.
Change-Id: Idcb4d11f7ff9867dfe29b47dcfd9774ed269ab3e
Closes-Bug: #1756464
* Update api-wg from branch 'master'
- Fix the checking of directories for extensions
The test for file extensions was checking everything returned by
glob.glob("guidelines/*"). The recent merge of the refactored HTTP
guidelines added a new guidelines/http/ directory, and the test was
failing because that entry didn't end with either .rst or .json. This
patch corrects that by skipping directories from that name check.
Change-Id: I0a84160015e9c1d96cb456b07c5e45fc6645df08
* Update api-wg from branch 'master'
- Break up the HTTP guideline into smaller documents
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
* Update api-wg from branch 'master'
- Merge "Add guideline on exposing microversions in SDKs"
- Add guideline on exposing microversions in SDKs
Change-Id: I69651d9df572bb33ea4fb413c57a4c3d15c98d7e
* Update api-wg from branch 'master'
- Correct header on time based filtering
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
* Update api-wg from branch 'master'
- Merge "Expand note about rfc5988 link header"
- Expand note about rfc5988 link header
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
* Update api-wg from branch 'master'
- Change API-WG to API-SIG
This updates as many references to 'API-WG', 'API Working Group', etc.,
to reflect the name change to the API-SIG.
Change-Id: I15ca0860c58bd7ba51f08dd39e551a774d7a060a
* Update api-wg from branch 'master'
- Merge "Remove the Nova liaison"
- Remove the Nova liaison
The liaison for Nova, Matthew Gilliard, no longer works on OpenStack, so
this removes him as the Nova liaison. This entry will remain empty until
Nova selects a new liaison.
Change-Id: I6723410b8fc4edf426237bdfe584efa2d59d8255
* Update api-wg from branch 'master'
- Merge "Explain, simply, why extensions are bad"
- Explain, simply, why extensions are bad
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
Project: openstack/api-wg 200e122d3017be4c535e736f2d30bc2c8f397080
Fix typo in liaisons.json
The previous update to this file switched the order of two rows, making
the text invalid JSON. This commit simply fixes that.
Change-Id: Ibb680c3f0f20e959c7171209980c53274df301b8
Project: openstack/api-wg 35c997e9ec9a8bbec00b0b4e94447a49a2ccd070
add a document for guided review process
This change adds the first draft revision of the guided review process
document. It also slightly reorganizes the table of contents links for
guidance on the index page to make it clear which guidance is for API
issues and which are for working group process issues.
Change-Id: Ifd7c7dce7f61bc57555e3bd2abac2703c1c7b6a3
Project: openstack/api-wg e9be2965b289a07746521f2985144525dd7f3908
Update compatibility doc and references
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
Project: openstack/api-wg 8b16c92912f81097a9839fb60dcfc947ae8a92b9
Fix service-types-authority schema URL and typos
In the consuming-catalog spec:
- Correct the URL pointing to the schema for service-types.json
- Minor typographical fixups
Change-Id: I4b5b81c64e55a16d05923da447d1c9544aea99b8
Project: openstack/api-wg 12bf769d63859000d9c1ef92201924e1ee93d7dd
Fix html_last_updated_fmt for Python3
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
Project: openstack/api-wg b41c61621071a3df59506b5cad9cc5ddaf8c1b54
Fix missing close bracket
Just a simple typo fix.
Change-Id: Iaec5e2d69f78116d0394a6212a4cf0173d8ba5c0
Project: openstack/api-wg d58443bf25590cab860c7979d0ee6d14b8c1d6d8
Microversions: add next_min_version field in version body
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
Project: openstack/api-wg a4e5fcf4fd8c600318f65e1c3f00ce800fae3061
Update Liaison Information
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
Project: openstack/api-wg 028d6012ab05a132467f316f3574fb6568bc2e57
Describe the publication of service-types-authority data
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
Project: openstack/api-wg 8e3e7afba5fc8c6a1091fe58edbfed202c7b98a5
Add support for historical service type aliases
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
Project: openstack/api-wg fa4d5f739dbb0d9f32e97c98a0ddadd9b08e837a
Add guideline about consuming endpoints from catalog
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
Project: openstack/api-wg ab7d331bd17a7e4a00116bcec164dff81ed801f3
Print name of violating file in unittest
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
Project: openstack/api-wg cc78247fef44cc9dc152e89383bd588eaadea068
Create a set of api interoperability guidelines
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
Project: openstack/api-wg 20469945070e55174407b1448722522e755de068
Recommend the correct HTTP method for tags
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
Project: openstack/api-wg 9cb7607028ba6b18f8a2f84ddb0755ae0b229a45
Define pagination guidelines
Co-Authored-By: Ron De Rose <ronald.de.rose@intel.com>
Co-Authored-By: Ian Cordasco <graffatcolmingov@gmail.com>
Change-Id: I0daac580155e98555a3775de4cb3923d519df503
Project: openstack/api-wg 7bfc3f37068d95a056da261539d06150bee95878
Remove reference to nova on version discovery
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
Project: openstack/api-wg ddc2f166dd76902e13eceaf0ecff5905214e1391
Clarify the meaning of BODY
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
Project: openstack/api-wg 33293c07645d5a1cde05058e8f169d4b8448863e
Clarify the status values in versions
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
Project: openstack/api-wg bab2a6b5b57c69442888cf2f6f18a6feab491745
Add guidelines on usage of state vs. status
This patch adds guidelines for when to use the name 'state' vs. when to
use 'status'.
Closes-Bug: #1593313
Change-Id: Ie32387ae6330562fdf0ba4158017dcf2a73b0eef
Project: openstack/api-wg c04450569b1971d3b2df4874cc5ebc3d89460026
Add guideline for invalid query parameters
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
Project: openstack/api-wg 0fccd41ef206990660bbfdf00cdc39f3570364a0
Removes unnecessary utf-8 encoding
The conf.py file was added redundant utf-8 encoding by some editor.
we can delete it.
Change-Id: If2f15027e6f0f0dd8e9e649ff56af4324cf4f8db
Project: openstack/api-wg 6ccd565824bfc1fc0e22c547c0ab65e340e6bdb8
Trivial fix: correct names of capitalization styles
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
Project: openstack/api-wg e01a677e96d36c7885e262a207fbb66c23e18b99
Add clarification on 400 vs. 404 guideline
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
Project: openstack/api-wg 03b5bdd43085114fa162df7f47e2263af11d5b2b
Add the operator for "not in" to the filter guideline
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
Project: openstack/api-wg fb2eb9f3b90f93169fcfea0dc3ce8d11d750dd1c
Change ironic liaison from lucasagomes to vdrok
This changes the ironic liaison to the API Working Group,
from Lucas Gomes to Vladyslav Drok.
Change-Id: Ic84bc088b7c13a9b45ba9c70f60e7b175c8f850c
Project: openstack/api-wg e3c0508bacba96a74e0ef2c167cf6a9d64cddf0c
Specify time intervals based filtering queries
This change introduces ISO8601-like time interval queries support.
Change-Id: I847dce368f74d021d6c2004bd6609b87e1c487a4
Project: openstack/api-wg 05fc0f2f048c798f9df8ac0f3176ab3ef6d52baf
Clarify why CRUD is not a great descriptor
Especially with regard to understanding POST.
Change-Id: I144a467b1ffa9a625fd00171898de52f41475c13
Closes-Bug: 1633478
Project: openstack/api-wg 2634c201d49abefd0692374dba579ad173fc81a7
Add guidelines for complex queries
This patch adds additional information regarding best practices when
requesting resources that are filtered by multiple values. It also
strengthens the admonition not to use request bodies with methods that
do not support request bodies.
Change-Id: I66081f25e16c82ee0350a9fb48e1d9f485e44ef6
Project: openstack/api-wg 0a3a901dd27d72df8e3ebbdbd0bb80480ba02758
Fix list formatting problem in microversion guideline
Some incorrect formatting for a nested list was present.
That has been corrected.
Change-Id: I5c18d6dee66f88b360c62dabbbbe37f0892f7b36
Closes-Bug: #1634554
Project: openstack/api-wg 5e720b7b1596e1e5501dea493bc9471bf3fc69fc
Update and correct links in README
The README had not been providing a link to the published guidelines
and an existing link was in markdown format, not RST.
Change-Id: I08ad96ae91f4bb9c13cdb449d1f76a72dd1c1b9a
Closes-Bug: #1632435
Project: openstack/api-wg 64e3e9b07272f50353429dc51d98524642ab6d67
Add the beginning of a set of guidlines for URIs
This guideline claims that effective URI design is critical to
effective APIs and lays in some initial groundwork for gathering
good advice on how to do it, starting with some suggestions on
how to do deal with collections in URIs
Change-Id: I9cd6b752ddb11597180ca22ce6326dda2a3311e2
Project: openstack/api-wg 49b3549e3dfaaf5590066222ea5a82f539a66be3
Clear the case if the version string isn't parsable
There isn't clear description what should be returned when the
version string isn't parsable. This patch clears about that.
Change-Id: I7bf6b28cf1d6f30ea0cb300b2da7cc05a1971c4e
Monty Taylor