The following attempts to be a summary of some of the API-WG related
ativity from last week's PTG. Despite some initial lack of
organization we managed to have several lively discussions in a room
that was occasionally standing room only.
I had intended to do a daily summary of my time at the PTG but
completely failed to do so. As with most OpenStack gatherings the
time was very compressed and completely exhausting. Fellow API-WG
core Ed Leafe manage a blog posting which includes some summary of
the API-WG period:
https://blog.leafe.com/atlanta-ptg-reflections/
We had initially planned to share a room with the architecture
working group, but at the last minute a room of our own (Georgia 5)
was made available to us. This led to some confusion on where people
were supposed to be when, but through the judicious use of IRC,
signs in the hallway and going and finding people who might help
with discussion, we managed to keep things moving. There also seemed
to be a degree of "I don't know where else to be so I'll hang with
the API-WG". This turned out to be great as it meant we had a lot of
diverse participation. To me that's the whole point of having these
gatherings, so: great success.
Because of sharing rooms with the arch-wg we also shared an initial
etherpad with them:
https://etherpad.openstack.org/p/ptg-architecture-workgroup
On there we formed an agenda and then used topic based etherpads for
most discussions:
* stability and compatibility guidelines:
https://etherpad.openstack.org/p/api-stability-guidelines
* capabilities discovery:
https://etherpad.openstack.org/p/capabilities-pike
* service catalog and service types:
https://etherpad.openstack.org/p/service-catalog-pike
with some discussion for how/when to raise the minimum microversion
happening on the architecture etherpad.
Sections for each of these below.
# Stability/Compatibility Guidelines
https://etherpad.openstack.org/p/api-stability-guidelines
This topic was discussion related to the updates being made to the
guidelines for stability and compatibility in APIs happening at
https://review.openstack.org/#/c/421846/
There are plans for this to become the guidance for a voluntary tag
that asserts a service's API is stable. The passionate discussion
throughout the morning and into the afternoon was in large part
reaching some agreement about the similarities and differences in
meaning of the terms "stability", "compatibility" and
"interoperability" and how those meanings might change depending on
whether the person using the term was a developer, deployer or user
of OpenStack services.
In the end the main outcomes were:
* The definitions that matter to the terms above are the ones that
impact the end user and that if we really want stability and
interoperability for that class of people, change of any sort that
is not clearly signalled is bad.
* Though microversions are contentious they are the tool we have at
this time which does the job we want. However, care must be taken
to not allow the presence of microversion to license constant
change.
* It's accepted and acknowledged that when a service chooses to be
stable it is accepting an increased level of development pain (and
potential duplication and cruft in code) to minimize pain caused
to end users.
* A service should not opt-in to stability until it is actually
stable. A service which is already stable, but wants to experiment
with functionality that it may not keep should put that
functionality on a different endpoint (as in different service).
* People who voiced strong opinions at the meeting should comment on
the review. Not much of this has happened yet.
* Strictness in stability is more important the more "public" the
interface is. A deployer only interface is less public.
* It is considered normal practice to express a potentially
different version with each different URL requested from a
service. What should be true is that if you take that exact same
code and use it against a service that supports the same versions
it should "just work" (modulo policy).
* Supporting continuous deployment is part of the OpenStack way.
This increases some of the developer-side pain mentioned above.
* We should document client side best practices that help ensure
stability on that side too. For example evaluating success as 200
<= resp.status < 300 instead of just 200 or 202 or 201 or
whatever.
* The guideline should document more of the reasoning.
So: we landed somewhere pretty strict, but that strictness is
optional. A project that wants the tag should follow the guidelines
and a project that eventually wants the tag or wants to at least
strive for interoperability should be aware of the guidelines and
implement those it can.
Next Steps:
* People comment on the review
* I produce a next version of the guidelines integrating the
feedback.
# Capabilities Discovery
https://etherpad.openstack.org/p/capabilities-pike
