API Deprecation Communication | API Design Language Exercises

1 / 5

An API team is planning to retire the v1 /auth/token endpoint. Which sequence correctly describes the standard API deprecation lifecycle?

Option B describes the industry-standard deprecation lifecycle. Skipping phases creates consumer trust problems and potential business and contractual damage for external APIs:

Phase	What happens	Consumer action
1. Announcement	Deprecation notice published: changelog, email, dashboard banner, API docs updated	Begin planning migration
2. Soft deprecation	Endpoint still works; `Deprecation` header added to responses; warnings in developer console	Monitoring tools alert engineering teams; migration begins
3. Sunset date published	`Sunset` header added to responses; final notices sent	Complete migration before the date
4. Hard removal	Endpoint returns 410 Gone or is removed from routing	Any remaining integrations break — migration window has closed

Timeline guidance: For widely-used public APIs, 6–12 months between announcement and hard removal is standard. For internal APIs with known consumers, 90 days is often sufficient. For APIs with large enterprise customers or SLA obligations, longer timelines and direct migration support may be required.

2 / 5

An API starts returning two response headers: Deprecation: Sat, 01 Jan 2026 00:00:00 GMT and Sunset: Sat, 01 Jul 2026 00:00:00 GMT.

What information do these headers communicate to API clients and their tooling?

Option D correctly describes both headers. The Deprecation and Sunset headers are defined in IETF drafts (draft-dalal-deprecation-header and RFC 8594) and are specifically designed for machine-readable deprecation signalling:

Header	Value format	Meaning
`Deprecation`	HTTP-date or `true`	This endpoint is deprecated as of this date. Begin migration.
`Sunset`	HTTP-date	This endpoint will be removed on or after this date. Hard deadline.
`Link` (companion)	`rel="deprecation"` or `rel="successor-version"`	Link to documentation about the deprecation or the replacement endpoint

Why headers beat documentation alone: Deprecation headers can be parsed programmatically — API observability tools (Datadog, New Relic, custom dashboards) can automatically detect when a service makes calls to a deprecated endpoint and alert the owning team. This is far more effective than expecting developers to read changelogs proactively.

3 / 5

A deprecation notice for the v1/orders endpoint includes a link to a "migration guide." What must a migration guide contain to be genuinely useful to API consumers?

Option A describes the complete migration guide standard. A migration guide is a separate deliverable from the API reference — it is a step-by-step transition document, not a specification replacement.

Migration guide section	What it must answer
Overview of changes	What changed and why — gives consumers context for the migration scope
Field mapping table	Old field name → New field name / Removed (no replacement) / Consolidated into X
Code examples	Before/after code in the languages most commonly used to call the API
Auth changes	If authentication or scopes changed, the migration of auth is often the hardest part
Timeline	Exact dates for each deprecation phase; no ambiguity
Support channel	Where to ask questions: Slack channel, support email, office hours

Why pointing to the reference doc is insufficient: Consumers already know the v2 reference doc exists. What they need is the delta — specifically what they need to change in their existing integration. A good migration guide takes 80% of the work out of migration planning.

4 / 5

A public API with 5,000 registered third-party developers is being deprecated. Which notification strategy is most appropriate?

Option C describes the multi-channel approach required for a public API deprecation at scale. No single communication channel reaches all developers:

Channel	Who it reaches	Coverage gap if omitted
Direct email to registered devs	Developers who provided an email on signup	Developers who don't monitor changelog or HTTP headers
Changelog / release notes	Developers who actively monitor changelogs	Most developers don't check changelogs proactively
Developer dashboard banner	Developers who log in to the portal	Developers using only API keys without portal access
HTTP deprecation headers	Automated monitoring tools in developer systems	Teams without automated API monitoring

High-usage consumer support: Developers with thousands of daily API calls should receive proactive outreach — an account manager contact or dedicated Slack channel. A large enterprise consumer breaking after sunset can create significant business impact for both parties.

5 / 5

An API team is renaming the required request field customer_id to account_id in the POST /orders endpoint. Which announcement phrase most accurately communicates the impact to consumer engineering teams?

Option B is the correct announcement format for a breaking change. It contains every element a developer team's engineer needs to act on immediately:

Element	Example in Option B	Why it's required
Breaking change label	"Breaking change:"	Engineers scan changelogs for this keyword — it must be prominent
Specific change	"'customer_id' renamed to 'account_id' in POST /orders"	Engineers need to know exactly what changed to assess their specific integration
Failure mode	"will receive 400 Bad Request"	Engineers need to know what their integration will do if they don't act
Effective date	"after [date]"	Gives a clear deadline for sprint planning and prioritisation
Action required	"update your integration to use 'account_id'"	Removes ambiguity about what the developer must actually do
Migration guide link	"See migration guide at [link]"	Points to detailed instructions without requiring the announcement to be exhaustive