Open Stack

Greetings OpenStack community,

In today's API-WG meeting we renamed the group twice. First to the "microversion support group". This is because any conversation that is even tangentially related to microversions becomes rather involved, leaking into metaphysics. Today involved some discussion on when a new or experimental service might like to turn them on (if they ever plan to do so). The advice here is to implement version discovery and versioning from the outset but don't start regularly bumping versions until after there has been an official release. There's some discussion of this topic in the interoperability guideline (linked below), which also happens to have been renamed (from "compatibility" to "interoperability").

The second group rename was to "Human Programming Interface Working Group" due to a discussion on whether to use a 404 or 400 in the case of a bad marker when doing pagination on a collection (guideline also linked below). 404 can be interpreted as strictly correct, especially from the standpoint of thinking of URIs as relatively strongly typed things. 400 may make more sense, however, to humans.

Both of these guidelines are subject to some debate, so if you have thoughts about them, do everyone a great favor and provide your input.

Thanks to members of the Sahara project for coming to speak with the API-WG, it made for some very interesting and fun discussions. We hope we were able to provide some useful input.

# Newly Published Guidelines

Nothing new this week.

# API Guidelines Proposed for Freeze

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

None this week, although the pagination guideline below is close.

# Guidelines Currently Under Review [3]

* Define pagination guidelines
   https://review.openstack.org/#/c/446716/
     Stuck on whether to use 400 or 404.

* Create a set of api interoperability guidelines
   https://review.openstack.org/#/c/421846/
     This has been renamed to indicate its focus more clearly.

* Microversions: add next_min_version field in version body
   https://review.openstack.org/#/c/446138/

* Mention max length limit information for tags
   https://review.openstack.org/#/c/447344/

* Recommend the correct HTTP method for tags
   https://review.openstack.org/451536
     Very close but needs more eyes.

* Add API capabilities discovery guideline
   https://review.openstack.org/#/c/386555/
     On hold.

* 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 WG, 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 WG mission and the work we do, see OpenStack API Working Group [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

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

-- 
Chris Dent                 ¯\_(ツ)_/¯           https://anticdent.org/
freenode: cdent                                         tw: @anticdent