The API is the foundation of all user interaction with OpenStack. It’s fundamental to the usability of OpenStack as a platform. A well designed and consistent API across all OpenStack projects is necessary, otherwise all of the layers above the API (SDKs, CLIs, Web Apps, Mobile Apps) suffer. As such, the OpenStack API Working Group (WG) has a clear mission.
To improve the developer experience of API users by converging the OpenStack API to a consistent and pragmatic RESTful design. The working group creates guidelines that all OpenStack projects should follow for new development, and promotes convergence of new APIs and future versions of existing APIs.
But things weren’t always so clear! As the API WG approached OpenStack projects we often faced the question, which can be paraphrased as, “Who are you and what are you trying to do to my API?!?!!” This left the WG members asking the same question of ourselves. Thus the mission statement was hammered out in a patch set and on the openstack-dev mailing list. It was a necessary detour from the regular business of creating guidelines to ensure that everyone within the group had the same vision of our mission and that we could clearly communicate that mission out to the OpenStack projects.
The Kilo Release Cycle
The API Working Group was founded by myself, Jay Pipes, and Chris Yeoh shortly before the Kilo Summit so it has only been in existence for a little over 6 months. In that time we’ve established our purpose, communication channels, deliverables, how to contribute, and scope in the API Working Group wiki page. In terms of our deliverables, we analyzed current API design, created guidelines, and reviewed API impacting code.
By the numbers:
- 9 current design analysis wiki pages
- ~10 guidelines
- ~170 API impacting change requests
- ~50 API impacting change requests reviewed
The number of guidelines could have been higher but a significant amount of time was spent establishing our identity as a group and how we will work together. It’s also heartening to see that there are already more than 10 guidelines up for review. We’ll be guaranteed to at least double our guideline output for the next cycle.
I also want to call out that we added a new core member to the project during Kilo. Please welcome Michael McCune to the API WG core team!
We also gained a lot of traction in the OpenStack projects during this time. Here are some select quotes.
-
“I like this, many thanks.” - John Garbutt, Nova PTL
-
“I also seek feedback from the API-wg” - Salvatore Orlando, Neutron Core
-
“I would like to get the advise of the Openstack Community and the API working group on how PATCH semantics should work.” - Amit Gandhi
-
“dovetails with developer focused API errors” - Rochelle Grober, Logging WG
This last quote has particular relevance as we move into the Liberty Release Cycle.
The Liberty Release Cycle
There is a lot of work to do and a lot we can improve upon in the coming release cycle. One of the most promising improvements to date has been how the OpenStack Nova project has defined the responsibilities of their liaisons. These Nova project members, Matthew Gilliard and Alex Xu, now have a clearly defined process for interacting with the API WG. I think this is a process that could be generalized for all projects willing to commit someone to this role.
There are also many other areas ripe for improvement.
- Meeting times
- Finding more traction
- Writing more guidelines
- Publishing the guidelines
- Formalizing the merge process
- Getting projects to implement the guidelines
- Using the guideline template
- The educational aspect of the API WG
We’ll be discussing these areas at the Liberty Summit in Vancouver over the course of 3 design sessions.
- API Working Group: State of the Group
- API Working Group: Working Session 1
- API Working Group: Working Session 2
There are also 2 summit sessions related to the API WG.
If you’re attending the summit, we hope to see you there!
Coda
If you’re a user of an OpenStack cloud, you care about the API, whether you know it or not. Poorly designed and inconsistent APIs manifest themselves as incomprehensible errors, incompatibilities, and bugs in other interfaces. If well designed and consistent APIs matter to you, here’s how to join the OpenStack API Working Group.