Governance/Proposed/APIManagement

Time: 2011-08-30 17:50:11

Drafter: JorgeWilliams

Drafters Email: <jorge DOT williams AT rackspace DOT com>

Status: To be completed by POC

API Management Proposal

Motivation

Recently, there has been increasing disagreement about the management of OpenStack APIs. Many feel that the current process is too restrictive, and have advocated allowing project teams free reign over API design, since they have the best interests of the project at heart, and they need the ability to rapidly evolve the design of a project. Others have argued that some level of consistency between APIs is necessary, and that users of the OpenStack APIs need an advocate to assure that their needs (e.g., for backwards compatibility between releases) is met. Both perspectives are valuable. OpenStack is still a young project, and stifling its growth at an early stage can be harmful. On the other hand, some amount of coordination and guidance can avoid serious problems for users and future releases. This document proposes a mechanism for guiding the development of OpenStack APIs that is significantly lighter-weight than our current approach. Specifically, it places the final responsibility for APIs in the hands of their Project Technical Leads, but provides for inter-project coordination through a new role, the API Coordinator. If approved, it's suggested that this process will be announced at the Essex Design Summit.

Proposal Summary

  1. The design and documentation of APIs for projects are owned by their respective Project Technical Leads.
  2. The Policy Project Board will nominate an "API Coordinator" who is charged with:

    1. Gaining consensus within the community on a set of general goals for OpenStack APIs, and a set of more specific guidelines to realise these goals.

    2. Working with individual projects to help them incorporate the guidelines, by consulting with them during API design, providing tests and tools, etc.
    3. Verifying that APIs are conformant with the guidelines when a milestone is branched.

Details

OpenStack API Goals

API Goals are shared attributes of the OpenStack APIs that are broadly agreed to be desirable. For example, a goal might be "Stability", with an explanation stating that "Users have a reasonable expectation that the API will not change in backwards-incompatible ways between releases, unless managed as part of a major API revision (which should be rare)." Goals for OpenStack APIs should focus on user outcomes and the overall OpenStack project goals. The API Goals will be gathered by the API Coordinator and submitted to the PPB for approval. Future revisions must also be approved. When finalized, the API Goals will be published on the OpenStack Wiki, and updated as necessary.

OpenStack API Guidelines

API Guidelines are patterns of use and testable properties that measurably help meet the API Goals. Guidelines do not specify project functionality, or decide whether a feature should be in the core API or an extension. Whenever possible, testable guidelines shall be preferred. For example, this guidelines is testable::

"JSON boolean values should not be encoded as strings."

A developer can easily write code to test conformance to this guideline. Whereas this is not::

"JSON requests and responses should be JSONic."

Non-testable guidelines are open to interpretation, usually lead to debate, and can often be decomposed into many more useful testable guidelines. Every guideline must also give a rationale that explains its purpose, and the goals it helps meet. For example::

"JSON boolean values should not be encoded as strings."
Rationale: Statically typed languages will be forced to convert the value back to a boolean, affecting usability in those languages.

The API Guidelines will be gathered by the API Coordinator and submitted to the PPB for approval. Future revisions must also be approved. When finalized, the API Guidelines will be published on the OpenStack Wiki, and updated as necessary.

The API Coordinator

The Project Policy Board will nominate an "API Coordinator" to coordinate the development of OpenStack APIs across all projects. This person will be expected to perform multiple duties:

  1. Gather community input and distill it into a set of agreed-upon API Goals.
  2. Based upon the API Goals, gather community input and produce a set of API Guidelines.
  3. Maintain the API Goals and Guidelines, modifying them as necessary based upon community experience.
  4. Work with Project Technical Leads to help apply the API Guidelines to specific projects.
  5. Provide projects with tools and test suites to help with the application of the API Guidelines.
  6. Verify that APIs are conformant to the Guidelines when a project is branched for a release milestone, and take steps to isolate non-conformant portions before release.

The API Coordinator may enlist the help of others, but has final responsibility for performing these duties. The API Coordinator is expected to reflect broad community consensus in the API Goals and Guidelines. In other words, it is preferable for the results to be mildly objectionable to a large number of people, instead of being strongly objectionable to a fewer number of people. However, the API Coordinator may overrule strong objections on technical grounds, in particular when backing the OpenStack project goals and/or approved API goals (in the case of guidelines). If there is a disagreement with the API Coordinator's judgment, it can be raised to the PPB for consideration when the relevant document (goals or guidelines) is submitted for their approval. Likewise, the API Coordinator is expected to use sound technical judgement when working with projects; their participation should be driven by a combination of the API Guidelines and pragmatic technical judgement, rather than architectural purity for its own sake.

Impact upon OpenStack Projects

The design and specification of a project's API is controlled by its Project Technical Lead. They are solely responsible for determining what features are exposed in the API as core features, and what new features should be designated as extensions. The PTL may also decide to promote an existing extension to a core feature. In doing so, the PTL is responsible for assuring that the API being produced conforms to the API guidelines, by liaising with the API Coordinator. The PTL should engage the API Coordinator as early as possible in the process in developing a new API or changing an existing one; e.g., by including them on the notification list for the appropriate blueprint and/or bugs. Projects are also strongly encouraged to document APIs as early as possible; e.g., by sketching them out in a blueprint. The means of producing the document (e.g., source format) are determined by the PTL, but should be done in consultation with the Documentation Coordinator. It is expected that the interaction between the API Coordinator and project teams be largely collaborative, with the API Coordinator acting both as a subject matter expert regarding APIs and an advocate for the API's end users, and the project team representing expertise on the function of the API. The API Coordinator may establish tests or provide tools to assist in the development of APIs that conform to the guidelines; if so, projects will be encouraged to adopt them. Releases must document all of the APIs (and all versions of each API) that they ship. The API Coordinator, Documentation Coordinator and Project Technical Leads will coordinate to establish common structures and presentation for API documentation.

Wiki: Governance/Proposed/APIManagement (last edited 2011-09-06 20:47:58 by JonathanBryce)