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
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
Some incorrect formatting for a nested list was present.
That has been corrected.
Change-Id: I5c18d6dee66f88b360c62dabbbbe37f0892f7b36
Closes-Bug: #1634554
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
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
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
There isn't clear description what should be returned when the
version string isn't parsable. This patch clears about that.
Change-Id: I7bf6b28cf1d6f30ea0cb300b2da7cc05a1971c4e
As 'in' operator is being implemented in oslo.utils, usage of
backslash inside quotes for values of operator 'in' should be clarified.
Change-Id: If80d648674182ff9902a992cf3cec24daaad8040
Depends-On: I15236d28b2136153db093590fb4dae65a87eb3e3
Co-Authored-By: Alexis Lee <lxsli@hpe.com>
This makes it seem like the guidelines are not yet ready. They are
ready but they are also constantly evolving. We don't want people
to go away thinking we're not ready yet.
Change-Id: I41e5849ea9fe0e1ef39c485861dc6686e9df6f1d
The API-wg liaison task is unfortunately not compatible with
salv-orlando's schedule and its current involvement level in
Neutron. Therefore salv-orlando is removing himself from the
liaison list.
Neutron already has another liaison - Henryg.
Change-Id: Ief89d2035229f3ac880533e3dda32a0159a1d2f9
I had to read the original note four times before it made sense to me.
The problem, I think, was that it talked about 'old' and 'new' - but I
don't have enough context to immediately remember which is old and which
is new. Also, the new thing was first, and my brain wanted to make them
be listed in the opposite order. It was also unclear to me for a bit
which was the one I was supposed to use.
Address those concerns by rewording the note to be clear that the first
option is the desired one, and to refer to each of them as first and
second rather than old and new.
Change-Id: I1d51572eb57278e6b21224ca60516c528de42ee1
