Skip to main content

IPA-1 Improvement Proposal for APIs

IPA stands for Improvement Proposal for APIs, which is a design document providing high-level, concise documentation for API development. They are to serve as the source of truth for API-related documentation at MongoDB and how teams discuss and come to a consensus on API guidance.

The principles are not final and are subject to changes.

State

Adopt

Guidance​

  • IPAs must describe guidance on API design
  • IPAs should provide instruction for API producers to help write APIs that are:
    • Simple
    • Intuitive
    • Consistent
  • IPAs are linkable documents that reviewers can use as a source of truth in discussions

Process​

It is the goal for IPAs to be a collaborative effort within MongoDB; however, the API experience team will:

  • Be responsible for approving and curating IPAs
  • Guaranteeing the correctness of the IPAs
  • Managing the process by which IPAs are introduced, discussed, approved, or retired

At any point, any engineer may propose changes to existing IPAs or new IPAs. To manage this process, IPAs will have a well-defined state.

State​

As technology progresses, and we discover new or better ways to do things, some principles may evolve or be retired.

To facilitate discussions about how or when to use a principle, each one will be labeled with a state described as:

Experimental​

  • New IPAs must start as experimental
  • During this phase, API producers and API experience should collaborate to understand better:
    • Alignment with other IPAs
    • Technical implications and challenges, for example:
      • Versioning support
      • Adoption challenges
      • Testing plans
    • Possible proof of concepts
  • The principle may be subject to change based on feedback
  • API producers and API experience may decide if a principle is ready for adoption or instead be retired
    • IPAs that are retired during the experimental state are still valuable to keep to inform future decisions
  • IPAs that stay in the experimental phase longer than a year from its initial proposal must transition to the retired phase
    • This allows keeping focus on the correct set of IPAs and avoids documenting principals that may no longer be worth considering
  • Experimental must be documented using warning admonitions

Example:

:::warning[State]

Experimental

:::

Adopt​

The principle must be well-supported at the time of adoption, meaning that:

  • It must provide a clear “how-to” to support implementation
  • It may provide tooling support, where possible.
  • API producers must follow this principle for new resources
  • API producers must justify opting out
  • Adopt must be documented using info admonitions

Example:

:::info[State]

Adopt

:::

Deprecated​

  • A newer/better way may have replaced the principle
  • API producers should consider following principles in the “adopt” state
  • API producers may be able to use the principle in cases where there may not be a replacement available
  • Using deprecated principles for new resources is discouraged and considered opt-in
  • API producers must justify its usage
  • Deprecated must be documented using warning admonitions

Example:

:::warning[State]

Experimental

:::

Retired​

  • API producers must not use the principle for new resources or revisions
  • Refactoring existing resources that now follow retired principles to migrate to a principle in the “adopt” state may be considered
  • Retired principles are still useful to keep around
    • Historical reasons
    • Document how older APIs were designed and implemented
  • Retired must be documented using danger admonitions

Example:

:::danger[State]

Retired

:::

Further Reading​

GitHub Alerts