Versions in the path, Sunset headers, six months of notice.
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
Deprecationheader and aSunsetheader (RFC 8594) with a date at least six months ahead, and aLinkto 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.