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 of "does my project align with the guidelines?" and are intended to be hosted by the working group at the PTG meetups.

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