Jump to: navigation, search

Difference between revisions of "API Special Interest Group"

(→‎How to Contribute)
Line 106: Line 106:
 
* [mailto:graham.hayes@hp.com Graham Hayes]
 
* [mailto:graham.hayes@hp.com Graham Hayes]
 
* [mailto:christopher.lefelhoc@rackspace.com Christopher Lefelhocz]
 
* [mailto:christopher.lefelhoc@rackspace.com Christopher Lefelhocz]
 +
* [mailto:lucasagomes@gmail.com Lucas Alvares Gomes]

Revision as of 16:01, 6 November 2014

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.

Deliverables

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

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

How to Contribute

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

1. To contribute to the guidelines:

  1. Follow the Gerrit_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


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


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

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.

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.

Retrieved from "https://wiki.openstack.org/w/index.php?title=API_Special_Interest_Group&oldid=67394"