API Gateway Platform  ·  View 19 of 21  ·  Operations

The API Version Lifecycle

The product persists; versions do not. The loop closes at the centre.

Editable source SVG draw.io All views
Preview schema published General availability supported Successor canaried sticky split Deprecated headers + date Tail tracked callers named Sunset zero callers API product outlives versions promoted successor 100% weight date set pins expire surface freed The API Version Lifecycle Application we own Decision point Security / platform The loop closes at the centre: the product persists, versions do not. A sunset is reached by evidence of zero callers, or by a recorded override with a name on it. v 1.0 · owner Integration Platform Architecture · date 2026-09

Decisions

  • Sunset is gated on evidence — zero active callers — or on a recorded override with a name against it. A date alone is not a mechanism.
  • Per-tenant version pins are dated and expire. An undated pin is a permanent second API nobody decided to keep.
  • Deprecation is signalled on responses of the deprecated version, which reaches machines; the portal's active-caller view is what reaches people.

Assumptions

  • At most three concurrent live versions per API; two in the MVP.
  • Sunset notice period is set per product by its owner, not by the platform — the platform enforces whatever was published.

Risks

  • Gateway-side version translation (ADR-12) would let v1 be served from the v2 implementation and remove most of this loop. It centralises the work and the risk, and is deferred to Phase 3 for exactly that reason.
◀  Observability All views Security Trust Zones  ▶
Solution Architecture v1.0 · Google Cloud · Integration Platform Architecture · 2026-09 · 21 views · 18 architecture decision records19-api-version-lifecycle