← Tutti i modelli

Versioni nel percorso, header Sunset, sei mesi di preavviso.

Spec — API versioning and deprecation

Status: draft · Created: 2026-11-10

1. Context and goal

Clients build on a stable API version and get clear, early warning before anything they use goes away.

2. Functional requirements (EARS)

  • FR-1: THE SYSTEM SHALL serve each major API version under its own path prefix (/v1, /v2) and answer 404 for an unknown version.
  • FR-2: THE SYSTEM SHALL make only backward-compatible changes within a version, checked on every build by a contract test against the published schema of that version.
  • FR-3: WHEN an endpoint or version is deprecated, THE SYSTEM SHALL add a Deprecation header and a Sunset header (RFC 8594) with a date at least six months ahead, and a Link to the migration guide.
  • FR-4: WHEN a version is deprecated, THE SYSTEM SHALL email every client that called it in the last 90 days, and remind them 30 days and 7 days before the sunset date.
  • FR-5: THE SYSTEM SHALL count calls per client to each deprecated endpoint, so its owners can see who still depends on it.
  • FR-6: WHEN the sunset date has passed, THE SYSTEM SHALL answer 410 on the retired endpoints with a link to the migration guide.

3. Out of scope

  • Versioning by header or media type.
  • Evolution of a GraphQL schema.