REST API Deprecation and Sunsetting

Every API changes over time. Old endpoints give way to better ones, and unused features cost money to maintain. Removing something that clients rely on breaks their apps. Deprecation and sunsetting form a planned, polite process for retiring parts of an API.

The Closing Shop Picture

A shop that plans to close posts a notice weeks ahead, holds a final sale, tells loyal customers where to shop next, and locks the door on the announced date. Customers feel respected, and nobody gets surprised. Retiring an API follows the same path.

The Two Terms

Deprecation means "still works, avoid using it, and expect removal". Sunset means "stops working on this date". The time between the two gives clients room to migrate.

The Lifecycle

Active ──→ Deprecated ──→ Sunset date reached ──→ Removed
            │                     │
      announce + warn       return 410 Gone
      publish migration     with link to new version
      guide

Warning Through Headers

Machines read headers before humans read emails. Add standard headers to every response from a deprecated endpoint.

HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 30 Jun 2027 23:59:59 GMT
Link: <https://api.example.com/docs/migrate-v2>; rel="deprecation"
Link: <https://api.example.com/v2/orders>; rel="successor-version"

The Deprecation header flags the status. The Sunset header states the removal time. Link headers point to the migration guide and the replacement endpoint. Client libraries and monitoring tools can detect these headers and alert developers.

A Sample Timeline

When	Action
Month 0	Release the new version and announce the deprecation
Month 1	Add Deprecation and Sunset headers, and publish the migration guide
Month 6	Email active users, and show warnings in the developer dashboard
Month 11	Send a final reminder, and run short planned test outages
Month 12	Return 410 Gone with a message that links to the new version

Public APIs with many users deserve a long window, such as 12 months. Internal APIs may need only a few weeks.

Know Who Still Uses It

Track calls per endpoint, per version, and per client. Usage data shows who needs a personal reminder.

Endpoint /v1/orders   last 30 days
   Client A   120,000 calls   ← contact first
   Client B     3,400 calls
   Client C        12 calls

Contact the heaviest users directly. Their migration effort is the largest.

Write a Migration Guide

• List every change, from renamed fields to new status codes.
• Show old and new requests side by side.
• Explain the reason, such as better speed or safer authentication.
• Offer a test environment where developers can try the new version.
• Provide a contact for questions.

What Counts as a Breaking Change

• Removing or renaming a field, endpoint, or parameter.
• Changing a field type or format.
• Adding a new required request field.
• Changing the meaning of a status code or error format.

Adding optional fields or new endpoints rarely breaks clients, and teams can release them without a deprecation cycle.

The Final Response

HTTP/1.1 410 Gone

{
  "error": "endpoint_removed",
  "message": "This endpoint ended on 30 June 2027.",
  "documentation": "https://api.example.com/docs/migrate-v2"
}

A helpful final message beats a bare error. Developers who return after the date find the fix in seconds.

Common Mistakes

Silent Removal

Deleting an endpoint without warning breaks apps and trust. Always announce, warn, and wait.

Endless Deprecation

A deprecated endpoint that never ends piles up maintenance cost. Set a real date and keep it.

Announcing in One Place Only

Developers miss blog posts. Combine headers, email, dashboard notices, and documentation banners.