Greetings OpenStack community,
Chaotic but fun API-SIG meeting today. elmiko has done some review of the
long-in-progress microversion history doc [7] and reports that it is worth
finishing and publishing as a historical document explaining why microversions
exist. Having greater context on the why of microversions should help them feel
like less of an imposition.
We then discussed what sort of things, if any, the API-SIG should try to talk
about during the Forum in Vancouver. edleafe will seek out some SDK-related
people to see if we can share some time together. If you're reading this and
you have some ideas, please respond and tell us.
Then the long lost mordred returned from the land of zuul to discuss some
ambiguities in how services, code and configuration use the concept of version.
I have to admit that my eyes glazed over (with tears) for a moment through
here, but the outcome was that the best thing to do is not surprise the users
or make them do extra work. This will be encoded in a followup to the merging
guidance on SDKs.
elmiko had another report on research he was doing: He thinks he may have
figured out a way to deal with microversions in OpenAPI documents. I don't want
to oversell this yet, but if it works this could be combined with the pending
experiments to make structured data out of existing api-ref documents [8] to
auto-generate OpenAPI schema from documentation.
Then we looked at some pending guidelines (see below). One that stood out as
potentialy controversial is the use of service name or service type in errors
document [9].
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.
None this week.
# 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 the errors guidance to use service-type for code
https://review.openstack.org/#/c/554921/
* 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] https://review.openstack.org/#/c/528801/
[9] 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
--
Chris Dent ٩◔̯◔۶ https://anticdent.org/
freenode: cdent tw: @anticdent
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
