AIP Purpose and Guidelines (#1)
What is an AIP?
AIP stands for API Improvement Proposal, which is a design document providing high-level, concise documentation for API development. They are to serve as the source of truth for API design guidelines at Kong and the means by which API teams discuss and come to consensus on API guidance. AIPs are maintained as Markdown files in the AIP GitHub repository.
An API is any interface that we, or our customers, will rely on. This is typically a HTTP API, but also includes CLI interfaces and extension points for plugins.
Types of AIPs
There are several different types of AIPs, described below. The list of AIP types may evolve over time as necessary.
Guidance
These AIPs describe guidance on API design. These are provided as instruction for API producers to help write simple, intuitive, and consistent APIs, and are used by API reviewers as a basis for review comments.
Process
These AIPs describe a process surrounding API design. They often affect the AIP process itself and are used to enhance the way in which AIPs are handled
Stakeholders
As with any process there are many different stakeholders when it comes to reviewing and working with AIPs.
API Czar
The API Czar is the final decision maker on the AIP process at Kong. This role is currently filled by Michael Heap.
Technical leads
A technical lead is a role that exists at Google, but is not yet used at Kong. They are more empowered than editors, but the czar can still veto. Having a technical lead would make it more explicit who the point of contact is e.g.
If we choose to implement technical leads, this AIP will be updated.
Editors
The editors are the set of people who make decisions on AIPs. The general goal is that the AIP process is collaborative and that we largely work on the basis of consensus.
The list of AIP editors is currently:
- Enrique García Cota
- Karen Inman
- Hayden Lam
- Michael Fero
- Wanny Morellato
AIP editorship is by invitation of the current editors.
States
AIPs may exist in a variety of states as they work their way through the process. These are:
- Draft: The AIP is being discussed and interated upon, primarily by the original authors. Editors may get involved at this stage, but it is not necessary
- Reviewing: Once discussion on an AIP has concluded, but before it is accepted it moves to the "Reviewing" state. This is the final stage of review before the AIP is accepted, and requires approval from the API Czar
- Approved: Once an approved AIP has been agreed upon, it enters "approved" state and is considered "best current practice".
- Withdrawn: If an AIP is withdrawn by the author or champion, it enters "withdrawn" state. AIPs that are withdrawn may be taken up by another champion.
- Rejected: If an AIP is rejected by the AIP editors, it enters "rejected" state. AIPs that are rejected remain as a pull request, and provide documentation and reference to inform future discussions.
- Replaced: If an AIP has been replaced by another AIP, it enters "replaced" state. AIP editors are responsible to provide a notice explaining the replacement and rationale (the replacement AIP should also clearly explain the rationale).
Workflow
Proposing an AIP
In order to propose an AIP, open an issue to circulate the fundamental idea for initial feedback. Once reviewed, the editors will assign the proposal an AIP number and recommend that a PR is raised with implementation details.
Discussing an AIP
Once the PR is opened, the AIP author is responsible for championing the AIP and soliciting feedback from their peers and the editors. The AIP may be modified by submitting follow-up commits to the PR. Additional commits should not be squashed until the review is completed.
Accepting an AIP
To gain final approval, an AIP must be approved by an editor. If there are any requested changes by any editor, the proposal can not be accepted.
Once the AIP is approved, the status is updated and the PR is merged. New APIs are expected to adhere to all AIPs that have been accepted at the time they enter the design phase. Existing APIs are expected to adopt all accepted AIPs in the earliest possible next iteration.
Rejecting an AIP
If an AIP proposal is rejected, the issue should be labeled with rejected and closed with an explanation from an editor why the proposal was rejected. Proposals that are rejected may be proposed again in the future once 3 months has passed.
Replacing an AIP
If an AIP has been replaced by another AIP, it enters the Replaced state. Editors are responsible for adding a notice explaning the replacement, and the rationale behind it.
Sample AIP Flows
The following flows assume that a technical lead is in place. If that is not the case, the Czar plays the role of the technical lead (including in example 2 where the czar is the AIP author).
HTTP
- The team goes to implement pagination in their API but realises there's no AIP defining the contract
- The team raises an AIP issue proposing that we use offset pagination to allow a page count in the UI
- There is discussion around offset vs cursor pagination in the issue. A proposal to support both is put together, with clear definitions on when to use each
- The AIP author reaches out to an editor to be allocated an AIP number, and raises a PR
- The editors (minimum 1, but ideally multiple), HTTP TL and czar all review the proposal a final time
- The proposal is merged and marked as accepted
CLI
- We get a customer request to support environment variables for authentication in a CLI. We realise there is no AIP for how to handle credentials in CLIs
- The czar has bandwidth to pick this up, and creates an issue proposing that we support environment variables, a config file on disk and CLI flags
- The author of the CLI requests to switch the location of the config file from
~ in to XDG_HOME. The AIP author agrees
- The AIP is allocated an AIP number, and a PR is raised
- The editors and CLI TL all review the proposal a final time
- The proposal is marked as accepted
Footnotes
This process is heavily influenced by the Google AIP process