Guided Review Process¶
The API Special Interest 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. At a high level, these reviews are focused on the question “does my project align with the guidelines?” and are intended to be hosted by the API Special Interest Group at the PTG meetups.
On a more concrete level, the API Special Interest Group expects that reviews which are directed towards specific areas, or problems within, an API will garner the best results (e.g. “Is using a PUT request for updating these resources appropriate?”, “We are using GET requests to start server actions, is there a better alternative?”).
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:
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.
Are you unhappy with how some of your current API works? We could brainstorm ideas about making it more consistent and usable.
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:
Pick an area of your API to focus on (e.g. a specific resource type, an interaction that is troublesome or endpoints that could use clarification).
Prepare a document describing the API in question, this could be free-form or something more formal like an OpenAPI specification. This does not need to be an expansive document, but should help drive the review conversation and provide a reference for the reviewers to understand the flow of the API in question.
Then just show up to an API Special Interest 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 depending on the nature of your request to the group. You should expect to have clarification on the basic question of how close your API follows the API-SIG’s guidelines. But, the depth of your review will depend entirely on how big a request is made of the review group.
The preparations that a project team makes before the review process will have the largest effect on the expected outcome. Teams that are more specific and focused with their requests to the review group will most likely harvest the greatest fruits from this process.
When considering approaching the API-SIG 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.
After a review is completed, the API Special Interest Group will archive the general details of the review (e.g. “Team <X> requested a review of API features <Y> and <Z>. It was agreed that actions <A>, <B> and <C> are the best path forward”) and any artifacts that are generated during the process. This archive will exist in the same repository as the guidelines under a separate heading for reviews.
Example Review¶
TODO
