Skip to main content
Experimental

IPA-128: Stability Levels

  1. Every API version must declare an associated stability level that states the maturity, expected pace of change, and support policy for the API.

Guidance​

  1. API resources must indicate their stability level in their documentation.

  2. API resources must use one of these stability levels: preview, stable, deprecated, and sunset.

Preview​

A preview API resource undergoes rapid iteration based on user feedback.

  1. A preview API resource may be available only to a selected group of users.

  2. A preview API resource may introduce breaking changes without requiring a new version (IPA-120).

  3. For a preview API resource, a feedback mechanism must be established for users to report issues and suggest improvements.

  4. Consumers must not have any expectation of stability from a preview API resource.

  5. Consumers should not use a preview API resource in production.

Stable​

A stable API resource is production-ready and fully supported.

  1. A stable API resource must be available to all users.

  2. A stable API resource must not introduce breaking changes without requiring a new version (IPA-120).

    Depends on
    IPA 128: Must Use Defined Stability Level

  3. A stable API resource must maintain backwards compatibility (IPA-116) to ensure ongoing reliability.

  4. A stable API resource must remain supported until all users have migrated to an alternative version, or until otherwise agreed between API provider and customers.

Deprecated​

A deprecated API resource is still supported but is on its way to becoming sunset.

  1. A deprecated API resource may no longer receive backwards compatibility changes.

  2. A deprecated API resource must transition to sunset within an established timeframe.

  3. A deprecated API resource must provide the Deprecation HTTP response header (RFC 9745) to signal to consumers that the resource is deprecated.

  4. A deprecated API resource must provide the Sunset HTTP response header (RFC 8594) to signal to consumers when it will transition to sunset.

  5. Consumers should migrate from a deprecated API resource to the stable version.

Sunset​

A sunset API resource is no longer supported.

  1. A sunset API resource must return 410 GONE.

  2. Consumers must migrate from a sunset API resource to the stable version.

Further Reading​