Skip to main content

IPA-128: Stability Levels

State

Experimental

APIs version must provide an associated stability level that clearly states the maturity, expectations of changes and support policies related to the API. The stability level provides consumers with a clear understanding of what to expect when integrating or depending on a given API.

Guidance​

  • API resources must clearly indicate on their documentation their stability level.
  • API resources must use one of these stability levels: preview, stable, deprecated, and sunset.
  • A preview API resource undergoes rapid iteration based on users' feedback.
    • The API resource may be available only to a selected groups of users.
    • The API resource may introduce breaking changes without requiring a new version (IPA-120).
    • API producers must establish a feedback mechanism for users to report issues and suggest improvements.
    • Consumers must not have any expectation of stability.
    • Consumers should not use the API in production.
  • A stable API resource is a production-ready and fully supported API.
    • The API resource must be available for all users.
    • The API resource must not introduce breaking changes without requiring a new version (IPA-120).
    • The API resource must release backwards compatibility (IPA-116) to ensure ongoing reliability.
    • The API resource must remain supported until all users migrated to alternative versions, or until agreed between API provider and customers.
  • A deprecated API resource is still supported but must transition to sunset in the future.
    • The API resource may no longer receives backwards compatibility changes.
    • The API resource must transition to sunset within an established timeframe.
    • The API resource must provide the Deprecation HTTP Response header (RFC 9745) to signal to consumers that the resource is deprecated.
    • The API resource must provide the Sunset HTTP Response header (RFC 8594) to signal to consumers when it will transition to sunset.
    • Consumers should migrate to the stable version.
  • A sunset API resource is no longer supported.
    • The API resource must return 410 GONE.
    • Consumers must migrate to the stable version.

Further Reading​