API Versioning Documentation — Sunset, Deprecation & Migration
Learn vocabulary and patterns for documenting API versions: sunset headers, deprecation notices, migration guides, breaking change patterns, and version lifecycle language.
0 / 5 completed
1 / 5
What is the 'Sunset' HTTP header and how should it be documented in an API spec?
Sunset header (RFC 8594): 'Sunset: Sat, 31 Dec 2024 23:59:59 GMT' — tells consumers exactly when an endpoint will be removed. In OpenAPI, document it under the endpoint's response headers. Pair it with a Deprecation header and a Link header pointing to the migration guide. This gives clients programmatic access to the sunset date, enabling automated monitoring tools to alert engineers before their integrations break.
2 / 5
What is a 'breaking change' in API documentation vocabulary, and how should it be distinguished from a non-breaking change?
Breaking changes require a major version bump and migration guide: removing fields, renaming fields, changing a field from optional to required, changing response codes, removing enum values, changing authentication. Non-breaking (additive) changes can go in a minor version: adding optional request fields, adding new response fields, adding endpoints, adding enum values. Documentation should explicitly label each change in the changelog as BREAKING or NON-BREAKING.
3 / 5
What should a well-written API migration guide include when moving from v1 to v2?
Effective migration guide structure: (1) Summary of what changed and why. (2) Timeline: deprecation date, sunset date. (3) Breaking changes list with before/after examples. (4) Step-by-step migration for each changed endpoint. (5) Authentication changes if any. (6) Code samples in the languages your consumers use most. (7) FAQ for common migration questions. The goal is to make migration mechanical — a developer should be able to follow the guide without needing support.
4 / 5
What does 'deprecated' mean in API documentation, and how is it expressed in OpenAPI?
deprecated: true in OpenAPI marks an operation or parameter as deprecated. Generators render it with a strikethrough in docs. Best practice: add to the description: 'Deprecated. Use POST /v2/orders instead. This endpoint will be removed on 2025-01-01. See the migration guide: https://docs.example.com/migrate-v2.' Without a sunset date and replacement link, 'deprecated' alone is not actionable — consumers don't know when to act or what to migrate to.
5 / 5
What is the purpose of a 'version lifecycle' section in API documentation, and what stages does it typically document?
Version lifecycle stages help consumers plan: Alpha — breaking changes possible, no SLA. Beta — feature-complete, minor breaking changes possible, not for production. GA/Stable — production-ready, breaking changes only in major versions. Deprecated — fully functional, end-of-life date announced, migration guide available. Sunset — removed, endpoint returns 410 Gone with a body pointing to the replacement. Document the minimum notice period you guarantee before sunsetting (e.g., 'We provide at least 12 months notice before removing any GA endpoint.').