Open Stack

Greetings OpenStack community,

Another jovial meeting of the API-SIG was convened today. We began with a
few housekeeping notes and then moved into a discussion of the api-ref work
and how we might continue to assist Graham Hayes with the os-api-ref
changes[7] that will output a machine-readable format for the API schemas.
The group generally agrees that the SIG should continue to assist in moving
these changes forward, there are concerns about the inclusion of
microversions and how best to capture these, but for the time being the SIG
will engage with the review and the parties interested in seeing this work
through to completion.

We then talked about the new reviews which have been added recently to the
queue. The SIG has decided to freeze the proposed guidance[8] on exposing
microversions in SDKs created by Dmitry Tantsur. There is also a review[9]
from Ed Leafe to split up the current HTTP guidance document into separate
documents to help improve the readability and presence of this material,
this should be ready for freeze soon.

Lastly, we discussed a new bug[10] concerning how services should be
referenced in error messages. The current guidance specifies that a service
name should be used and the proposed bug by Chris Dent is that the service
type should be used instead. Chris has also created a review[11] to address
this but the SIG would like more opinions on this change and how it might
impact consuming the error messages.

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

None this week.

# API Guidelines Proposed for Freeze

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

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

# 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

* 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/#/c/528801/
[8] https://review.openstack.org/#/c/532814/
[9] https://review.openstack.org/#/c/554234/
[10] https://bugs.launchpad.net/openstack-api-wg/+bug/1756464
[11] https://review.openstack.org/#/c/554921/

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-sigs/attachments/20180322/a47e25e2/attachment.html>