API Deprecation Done Right

An API provider removed an endpoint with two weeks notice. A production integration broke. The developer team scrambled over a weekend to migrate. Their CEO wrote an angry email. The API provider apologized and offered a migration extension. Relationships suffered.

This story repeats across the industry. Deprecation is when API providers cause the most damage to developer trust. Get it wrong and you lose customers. Get it right and developers barely notice the transition.

We commit to a specific deprecation process at Nowah, and every step exists because we saw the alternative fail somewhere else.

The deprecation timeline

Our deprecation follows five stages with minimum time intervals between them:

Announce happens at least twelve months before removal. We publish the deprecation in our changelog, add documentation notes, and begin including deprecation headers in responses from affected endpoints.

Warn starts with dashboard banners and email notifications to every API key owner that has called the deprecated endpoint in the last 90 days. We do not guess who might be affected. We check actual usage data.

Sunset header appears in every response from the deprecated endpoint: `Sunset: Sat, 01 Mar 2027 00:00:00 GMT`. This is a machine-readable date that client libraries can parse and act on. Well-built SDKs can log a warning or even throw an exception when they detect a sunset header approaching its date.

Soft-disable returns a 299 status code with a deprecation warning but still processes the request. This is the "last chance" signal. The endpoint still works but is actively shouting that it is about to stop working.

Hard-remove returns 410 Gone. The endpoint is dead. The response body includes a link to the migration guide and the replacement endpoint.

The entire process spans at least twelve months. We have never needed to compress this timeline, and we would treat needing to as a sign that something went wrong in our planning.

Migration guides that actually help

When we deprecate an endpoint, we publish a migration guide that diff the old and new schemas. The guide is auto-generated from our OpenAPI specifications and then hand-reviewed for clarity.

Each guide includes the specific fields that changed, with before-and-after code examples in every SDK language. It includes a section on breaking vs. non-breaking changes so developers can prioritize their migration work. And it includes a testing checklist so developers can verify their migration against the sandbox before switching in production.

We also provide a compatibility mode where possible. If a field was renamed but not removed, we return both the old and new field names during the overlap period. This gives developers a graceful migration path where they can update their code to read the new field name while the old one still works.

Usage monitoring drives sunset decisions

We track per-API-key usage of deprecated endpoints. A dashboard shows the adoption curve: what percentage of traffic has migrated to the new version, and which specific API keys are still using the old one.

We do not remove an endpoint while significant traffic still hits it. If the sunset date is approaching and adoption of the new version is below our threshold, we extend the sunset date and increase outreach to the remaining users.

This data-driven approach prevents the worst deprecation outcome: removing something that people are still actively using. It also lets us identify developers who might be stuck — maybe they are not migrating because the migration guide is unclear, or because the new endpoint has a bug that blocks their use case. We reach out to those developers directly.

Proactive communication

Every stage of the deprecation lifecycle triggers communication:

• Announcement: changelog entry, documentation update, blog post if the change is significant.
• Warning: email to affected API key owners with the timeline and migration guide link.
• 90 days before sunset: reminder email with current usage data ("you made 4,200 calls to this endpoint last month").
• 30 days before sunset: urgent email with a direct offer to help migrate.
• Soft-disable: final email confirming the endpoint will stop working on the sunset date.

We over-communicate rather than under-communicate. The cost of sending one too many emails is a developer rolling their eyes. The cost of sending one too few is a production outage.

The checklist

If you are deprecating an API endpoint, here are the eight steps:

1. Publish the deprecation in your changelog with the sunset date.
2. Add `Deprecation: true` and `Sunset` headers to the endpoint's responses.
3. Publish a migration guide with before/after code examples.
4. Email every API key owner who has used the endpoint in the last 90 days.
5. Monitor per-key migration progress on a dashboard.
6. Send reminder emails at 90 days, 30 days, and 7 days before sunset.
7. Soft-disable with 299 status codes before hard removal.
8. Hard-remove with 410 Gone and a redirect to the migration guide.

Skip any step and you risk breaking someone's production system and their trust in your platform. The process takes effort, but the alternative is worse for everyone.

Deprecation is not a technical problem. It is a communication problem. The technical mechanism — sunset headers, version routing, migration guides — exists to facilitate communication between you and the developers who depend on your API. Treat it as communication and the technical details fall into place.

Nowah is an AI travel agent that searches and books real flights and hotels through conversation — no filters, no thirty open tabs. Plan your next trip.