Lifecycle

Breaking down the stages of the lifecycle across APIs, while also providing instances for individual APIs, with details of each stage, the policies and rules applied within each stage, and the progress that APIs are making throughout the lifecycle

Also known as: API Lifecycle, Maturity, Release Stage

Example

- type: X-Lifecycle
  url: https://developers.example.com/lifecycle

Standards

Community spec Semantic Versioning 2.0.0 (pre-release identifiers)
IETF RFC 9745 — The Sunset HTTP Response Header Field
IETF The Deprecation HTTP Response Header Field (draft-ietf-httpapi-deprecation-header)
Vendor guideline Microsoft REST API Guidelines
Vendor guideline Google API Improvement Proposals (AIPs)
Vendor guideline AIP-181 — Stability levels
OpenAPI Initiative OpenAPI Specification (info, deprecated)

HTTP Headers

Header	Direction	Spec	Description
`Sunset`	response	RFC 9745	Communicates the retirement date for an API or resource.
`Deprecation`	response	draft-ietf-httpapi-deprecation-header	Marks a resource as deprecated as it moves through the lifecycle.

OpenAPI Expression

info.x-lifecycle (Vendor extension) — Common extension to declare stage (alpha, beta, ga, deprecated, retired).
info.x-stability (Vendor extension) — Used by some providers (e.g. Google AIP-181) to signal stability level.
deprecated (OpenAPI 3.x) — Marks operations or schemas at the deprecated stage of the lifecycle.

Link Relations

sunset — RFC 9745
deprecation — draft-ietf-httpapi-deprecation-header
successor-version — RFC 5829

Governance Rules

naftiko-lifecycle (Naftiko Sandbox (lifecycle/*.yml)) — Rules that verify each API declares a lifecycle stage and that deprecated endpoints carry Sunset.
oas-info-description (Spectral built-in) — info.description should communicate stability and lifecycle expectations.
oas-operation-tag-defined (Spectral built-in) — Tags can encode lifecycle (e.g. beta) and must be defined consistently.

Risk & Compliance

Compliance:

SOC 2 CC8.1 — change management across release stages
ISO/IEC 27001 A.14.2 — security in development and support processes

Security: Mixing experimental endpoints with production traffic without clearly signalling stability invites consumers to depend on unsupported behaviour. A documented lifecycle with explicit alpha/beta/GA/deprecated/retired stages, plus enforced sunset windows, limits exposure to unsupported code paths.

Tools

Backstage — Catalog (Apache-2.0)
Spectral — Linter (Apache-2.0)
oasdiff — Breaking-change detector (Apache-2.0)
optic — Change tracking (MIT)

Suggested Metrics

apis_by_stage — Count of APIs in each lifecycle stage (alpha, beta, GA, deprecated, retired).
time_in_stage_median_days — Median dwell time per stage; surfaces stuck APIs.
beta_to_ga_conversion_rate — Share of beta APIs that reach GA versus being retired.
retired_traffic — Traffic still hitting retired endpoints; should trend to zero.

Example Implementations

Microsoft Graph — Explicit v1.0 (GA) and beta endpoints with documented promotion path.
Google — AIP-driven stability levels and launch stages (preview, GA, deprecated).
GitHub — Preview features with explicit opt-in media types until graduation.
Stripe — Public preview and beta product flags surfaced in documentation.