Open Stack

Greetings OpenStack community,

Today's meeting was quite lively with a good discussion about versions
and microversions across OpenStack and their usage within the API
schema world. We began with a review of outstanding work: elmiko is
continuing to work on an update to the microversion history doc[7],
and edleafe has reached out[8] to the SDK community to gauge interest
in a session for the upcoming Vancouver forum. dtanstur has also also
made an update[9] to the HTTP guideline layout that is currently under
review. The change was already largely approved; this just improves
the appearance of the refactored guidelines.

The API-SIG has not confirmed any sessions for the Vancouver forum
yet, but we continue to reach out[8] and would ideally like to host a
session including the API, SDK and user community groups. The topics
and schedule for this session will be highly influenced by input from
the larger OpenStack community. If you are interested in seeing this
event happen, please add your thoughts to the mailing sent out by
edleafe[8].

The next chunk of the meeting was spent discussing the OpenAPI
proposal[10] that elmiko has created. The discussion went well and
several new ideas were exposed. Additionally, a deep dive into
version/microversion usage across the OpenStack ecosystem was exposed
with several points being raised about how microversions are used and
how they are perceived by end users. There is no firm output from this
discussion yet, but elmiko is going to contact interested parties and
continue to update the proposal.

mordred informed the SIG that he has started working on
discover/version things in keystoneauth and should be returning to the
related specs within the next few days. and there was much rejoicing.
\o/

On the topic of reviews, the SIG has identified one[11] that is ready
for freeze this week.

Lastly, the SIG reviewed a newly opened bug[12] asking to add a
"severity" field to the error structure. After a short discussion, the
group agreed that this was not something that should be accepted and
have marked it as "won't fix". For more details please see the
comments on the bug review.

As always if you're interested in helping out, in addition to coming
to the meetings, there's also:

* The list of bugs [5] indicates several missing or incomplete guidelines.
* The existing guidelines [2] always need refreshing to account for
changes over time. If you find something that's not quite right,
submit a patch [6] to fix it.
* Have you done something for which you think guidance would have made
things easier but couldn't find any? Submit a patch and help others
[6].

# Newly Published Guidelines

* Add guideline on exposing microversions in SDKs
  https://review.openstack.org/#/c/532814

# API Guidelines Proposed for Freeze

Guidelines that are ready for wider review by the whole community.

* Update the errors guidance to use service-type for code
  https://review.openstack.org/#/c/554921/

# Guidelines Currently Under Review [3]

* Break up the HTTP guideline into smaller documents
  https://review.openstack.org/#/c/554234/

* Add guidance on needing cache-control headers
  https://review.openstack.org/550468

* Update parameter names in microversion sdk spec
  https://review.openstack.org/#/c/557773/

* Add API-schema guide (still being defined)
  https://review.openstack.org/#/c/524467/

* A (shrinking) suite of several documents about doing version and
service discovery
  Start at https://review.openstack.org/#/c/459405/

* WIP: microversion architecture archival doc (very early; not yet
ready for review)
  https://review.openstack.org/444892

# Highlighting your API impacting issues

If you seek further review and insight from the API SIG about APIs
that you are developing or changing, please address your concerns in
an email to the OpenStack developer mailing list[1] with the tag
"[api]" in the subject. In your email, you should include any relevant
reviews, links, and comments to help guide the discussion of the
specific challenge you are facing.

To learn more about the API SIG mission and the work we do, see our
wiki page [4] and guidelines [2].

Thanks for reading and see you next week!

# References

[1] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[2] http://specs.openstack.org/openstack/api-wg/
[3] https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
[4] https://wiki.openstack.org/wiki/API_SIG
[5] https://bugs.launchpad.net/openstack-api-wg
[6] https://git.openstack.org/cgit/openstack/api-wg
[7] https://review.openstack.org/444892
[8] http://lists.openstack.org/pipermail/openstack-sigs/2018-March/000353.html
[9] https://review.openstack.org/#/c/554234/
[10] https://gist.github.com/elmiko/7d97fef591887aa0c594c3dafad83442
[11] https://review.openstack.org/#/c/554921/
[12] https://bugs.launchpad.net/openstack-api-wg/+bug/1761475

Meeting Agenda
https://wiki.openstack.org/wiki/Meetings/API-SIG#Agenda
Past Meeting Records
http://eavesdrop.openstack.org/meetings/api_sig/
Open Bugs
https://bugs.launchpad.net/openstack-api-wg