Jump to: navigation, search

API Special Interest Group

Revision as of 20:06, 9 January 2015 by Everett Toews (talk | contribs) (Clarify scope and include API definition format)

Status: Forming

Organizers: Jay Pipes, Christopher Yeoh, Everett Toews

Purpose

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

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

Identifying code changes and specs that affect APIs will require some vigilance on the part of members. Previously identified changes should carry the APIImpact flag, which allows them to be discovered by searching for the APIImpact flag within gerrit. If they find a review that affects an API, they can email the openstack-dev list (using the [api] prefix) to notify the rest of the members of the review.

We should encourage all OpenStack Programs to adopt the use of an APIImpact flag in their commit messages.


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.


5. Bugs (DO NOT start doing this yet)

Let's not run around creating bugs for everyone just yet. How and when we start doing this should be determined in discussions in the meetings and on the list.

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 git clone git://git.openstack.org/openstack/api-wg.git
  3. Continue with the workflow for your change


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:
    1. Add comments to the review according to the guidelines.
    2. Link to the guidelines so the contributor can better understand your reasoning.
    3. Feel free to let the contributor know you are a member of the API Working Group.
    4. If the contributor disagrees with your review comments, invite them to start a thread on the openstack-dev mailing list with the prefix [api]
  3. 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 contribute bugs (DO NOT start doing this yet):

  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"


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

Scope

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.

How to Join

Join the openstack-dev mailing list, watch for emails that are prefixed by [api], and join the discussion.

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.