API Special Interest Group/Guided Review Process

Guided Review Process
NOTICE: This page is currently in the drafting process

Abstract
The API working group would like to increase the tools available to OpenStack project teams by defining a process and venue for conducting live face-to-face reviews. These reviews are focused on the primary question "does my project align with the guidelines?" and are intended to be hosted by the working group at the PTG meetups.

Ideal Candidates for Review
It may be difficult if not impossible to review the entire API of a project in a session at the PTG. So here are some suggestions for selecting discussion topics:
 * 1) Is there a part of your API that has generated some disagreement on your team? If so, that would be an excellent subject for discussion at the PTG.
 * 2) Are you unhappy with how some of your current API works? We could brainstorm ideas about making it more consistent and usable.
 * 3) Are you creating a new API? If you're starting a new project, or creating a new major version for your project, we can discuss what would be the most effective ways to approach it.

How do I get my project reviewed?
Here are some things you should prepare before approaching the API working group for a live review of your project:
 * 1) Pick a general area of your API to focus on (e.g. a specifc resource type, an interaction that is troublesome or endpoints that could use clarification).
 * 2) Prepare a document describing the API in question, this could be free-form or an OpenAPI specification. This does not need to be an expansive document, just something to help the reviewers quickly understand the flow of the API.
 * 3) Show up to an API working group face-to-face session with your materials ready, sending an email ahead of time will help to ensure that the group is ready for your review but is not strictly necessary.

What should I expect from my review?
The answer to this will vary slightly depending on the nature of your request to the working group. In general, you should expect to have a clarification on the basic question of how close your API follows the working group's guidelines.

When considering approaching the working group for a review, we encourage projects to identify areas of their APIs that could use clarification or have been problematic to the team. Project teams that have reviewed the API guidelines and have questions about specific areas of interest will find that their reviews will be more productive than open-ended questions which cover large portions of their API.

Example Review
TBD