API Working Group

Status: Active

Organizers: Chris Dent, Michael McCune, Ed Leafe

Purpose
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.

In general we propose, discuss, review, and advocate for API guidelines for all OpenStack Programs to follow. Any member of the working group is able to propose API guidelines. These proposals will be discussed by the working group. When a spec for an API schema is up for review (e.g. a Nova spec for one of the Nova API schemas), the working group members should review the spec and provide feedback with respect to how well it follows the guidelines. The working group members are also responsible for advocating for following the API guidelines within the OpenStack Programs that they work on.

How to Join
To join, add yourself as one of our Members and tune into any of our communication channels below. Reach out to us if you have any questions about How to Contribute.

Communication
For email, we will use the openstack-dev mailing list and prefix the subject line with [api]. Ideally, any OpenStack developer in any program that is discussing their API will also begin to use the [api] prefix so the working group members can be alerted to relevant discussions.

For IRC, we will use #openstack-sdks on Freenode.

For the OpenStack Summit, design summit sessions.

For meetings, the API Working Group meetings.

For cross-project liaisons (the liaison is the first line of contact for the API WG team members), see Cross-Project Liaisons

Deliverables
1. Analyze Current Design

This is essentially a way to record and visualize the current design of the APIs. It allows us to bring together many examples of the way APIs are designed so they can be analyzed and act as a discussion point. These are examples of good design to be emulated or bad design to be avoided. It can be examples of where the APIs are consistent or where there are inconsistencies.

2. Guidelines

Agreed upon and accepted guidelines must be added to version controlled documents in Git (GitHub mirror). Currently proposed changes to the documents can be found in this review report.

3. Reviews

Review comments and +1 or -1 votes on code changes and specs that affect any OpenStack Program API.

When code changes impact the OpenStack APIs and there are concerns about whether the changes are aligned with guidelines, members of the project should feel free to invite members of the working group to review. Either add group members to the review, send an email to the openstack-dev list with a tag of [api], or add a link to the weekly meeting agenda.

4. Announcement Email

When a new guideline has been accepted, it must be announced to openstack-dev (without the [api] prefix for more visibility). The email must include a link to the guideline and the history (links to the wiki and review) of how it came to be.

Starting with the Newton cycles, the working group is experimenting with a weekly newsletter email that will contain all the freeze announcements, as well as information about high priority reviews, and upcoming news from the working group. The template for the newsletter email can be found here: API Working Group weekly email template.

5. Bugs for the OpenStack API WG

Track work for new guidelines or major changes to existing guidelines.

6. Bugs for OpenStack projects

When a new guideline has been accepted, bugs can be filed against APIs that do not follow the guideline. If the bug forces a backwards incompatible change, it would have to be fixed in the next version or microversion of the API. The bug must include a link to the guideline.

How to Contribute
Contributions come in the form of the deliverables above. For deliverables 2 and 3, you'll first have to go through the If you're a developer section of How_To_Contribute.

1. To contribute to analyzing current design:


 * 1) Start at Current Design.
 * 2) Find the category of the API design you want to analyze. If it doesn't exist, create it.
 * 3) Edit the wiki page and do the analysis.

For example, you want to analyze the consistency of all of the APIs that do pagination. In the Pagination category, create a table that lists all of the ways APIs do pagination side by side.

2. To contribute to the guidelines:


 * 1) Follow the Development Workflow
 * 2) When you get to Project Setup, start with a
 * 3) Continue with the workflow for your change
 * 4) Use the Example Guideline Template when creating a completely new guideline

3. To contribute to reviews:


 * 1) Find a review on review.openstack.org that impacts any API (this review report).
 * 2) When commenting on the review:
 * 3) Add comments to the review according to the guidelines.
 * 4) Link to the guidelines so the contributor can better understand your reasoning.
 * 5) Feel free to let the contributor know you are a member of the API Working Group.
 * 6) If the contributor disagrees with your review comments, invite them to start a thread on the openstack-dev mailing list with the prefix [api]
 * 7) Vote +1 or -1 on the review

4. To contribute announcement emails:

If you've proposed a guideline and it has been accepted, send an email to openstack-dev to announce it (read #4 above).

5. To track work for new guidelines or major changes to existing guidelines:


 * 1) Go to The OpenStack API WG bug tracker.
 * 2) Search for a preexisting bug
 * 3) Create new bug if necessary

6. To contribute bugs for OpenStack projects.


 * 1) Find the project in Launchpad.
 * 2) Go to the bug tracker for that project
 * 3) Report the bug and be sure to click on Extra Options and include the tag "api"

7. Participate in the discussions at the weekly API Working Group meetings.

In Scope
The API Working Group is focused on creating guidelines for the HTTP APIs that expose the features to the application developers/operators using those APIs. It is not concerned with the implementation of those APIs.

These are guidelines for both going forward and for providing input (bugs) into the current version of existing APIs. When reporting bugs to the current version of existing APIs, the intent isn't to actually change the current version but to improve the next version of the API.

Recommending the use of an API definition format (e.g. Swagger, RAML, API Blueprint) to drive both the implementation of the service and the client.

Out of Scope
Third-party apis (e.g. EC2, S3, OCCI, etc.) are out of scope.

There is the related Application_Ecosystem_Working_Group (AE WG). The API Working Group (API WG) is complementary to the End User Working Group. The API WG is focused on creating guidelines for the APIs whereas AE WG is focused on creating applications that consume the APIs. The place where these groups meet in the middle is the API, which forms the contract between the two. Members of the AE WG are encouraged to be members of the API WG and vice versa.

FAQ
Q. My OpenStack Program doesn't have an API schema or a spec review process (like Nova's). What do I do?

A. Propose that your OpenStack Program adopt an API schema language and spec review process. The best way to give the API Working Group some teeth is by reviewing specs of API schemas. Commenting on reviews and giving a +1 or -1 to APIs that follow or don't follow the API guidelines will give this working group the potential to affect real change in OpenStack.

Members
Please add yourself to this list if you are committed to making the OpenStack APIs better.


 * Adrian Otto
 * [mailto:mr.alex.meade@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Alex Meade]
 * [mailto:soulxu@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Alex Xu]
 * [mailto:anne.gentle@rackspace.com Anne Gentle]
 * [mailto:apps.desh@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Apoorva Deshpande]
 * Brian Rosmaita
 * [mailto:bmorel@internap.com Bruno Morel]
 * [mailto:chdent@redhat.com Chris Dent]
 * [mailto:christopher@ansible.io Christopher Armstrong]
 * [mailto:christopher.lefelhoc@rackspace.com Christopher Lefelhocz]
 * [mailto:constanze.kratel@rackspace.com Constanze Kratel]
 * [mailto:dstanek@dstanek.com David Stanek]
 * [mailto:dtroyer@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Dean Troyer]
 * [mailto:deepak.mohan@rackspace.com Deepak Mohan]
 * [mailto:dolph.mathews@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Dolph Mathews]
 * [mailto:ed@leafe.com Ed Leafe]
 * [mailto:taget@linux.vnet.ibm.com Eli Qiao]
 * [mailto:eglynn@redhat.com Eoghan Glynn]
 * [mailto:erictchiu@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Eric Chiu]
 * [mailto:ericnielsenphd@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Eric Nielsen]
 * [mailto:ericnielsenphd@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Eric Nielsen]
 * [mailto:everett.toews@rackspace.com Everett Toews]
 * [mailto:ghanshyammann@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Ghanshyam Mann]
 * [mailto:gouthamr@netapp.com Goutham Pacha Ravi]
 * [mailto:gilles@redhat.com Gilles Dubreuil]
 * [mailto:graham.hayes@hp.com Graham Hayes]
 * [mailto:yanheven@qq.com Haifeng Yan]
 * [mailto:ian.cordasco@rackspace.com Ian Cordasco]
 * Jason Zhang
 * [mailto:jaypipes@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Jay Pipes]
 * [mailto:jxstanford@solinea.com John Stanford]
 * [mailto:oomichi@mxs.nes.nec.co.jp Ken'ichi Ohmichi]
 * [mailto:kevin.mitchell@rackspace.com Kevin Mitchell]
 * [mailto:lbragstad@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Lance Bragstad]
 * [mailto:lisa.clark@rackspace.com Lisa Clark]
 * [mailto:lucasagomes@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Lucas Alvares Gomes]
 * [mailto:maishsk@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Maish Saidel-Keesing]
 * [mailto:mark@mcclain.xyz Mark McClain]
 * [mailto:mm9745@att.com Matt McEuen]
 * Matthew Gilliard
 * [mailto:maty.grosz@alcatel-lucent.com Maty Grosz]
 * Melvin Hillsman twitter/irc - mrhillsman
 * [mailto:krotscheck@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Michael Krotscheck]
 * [mailto:msm@redhat.com Michael McCune]
 * [mailto:miguel.grinberg@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Miguel Grinberg]
 * [mailto:jianlonghei@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Park Hei]
 * [mailto:tengqim@cn.ibm.com Qiming Teng]
 * [mailto:ryansb@redhat.com Ryan Brown]
 * [mailto:shigematsu.mitsuhiro@lab.ntt.co.jp SHIGEMATSU Mitsuhiro]
 * Salvatore Orlando
 * [mailto:sam.harwell@rackspace.com Sam Harwell]
 * [mailto:shaunak.kashyap@rackspace.com Shaunak Kashyap]
 * [mailto:steve.lewis@rackspace.com Steve Lewis]
 * [mailto:tinlam@outlook.com Tin Lam]
 * [mailto:kaufer@us.ibm.com Steven Kaufer]
 * [mailto:yuntongjin@&#103;&#109;&#097;&#105;&#108;&#046;&#099;&#111;&#109; Yuntong Jin]
 * [mailto:zack.shoylev@rackspace.com Zack Shoylev]
 * [mailto:huangzhipeng@huawei.com Zhipeng Huang]
 * [mailto:jichenjc@cn.ibm.com jichenjc]
 * [mailto:flanders@openstack.org David F Flanders] Twitter/IRC-nick = @DFFlanders