About Endpoint Deprecation Tracker

Track API endpoint deprecation timelines with migration guides and sunset notifications. Part of the DevTools Surf developer suite. Browse more tools in the API / Config collection.

Use Cases

• Track deprecation timelines for multiple API endpoints across versions
• Generate RFC 8594-compliant Sunset and Deprecation response headers
• Communicate breaking changes to API consumers with structured timelines
• Monitor which deprecated endpoints are still receiving traffic before sunsetting

Tips

• Enter the Sunset date and migration deadline separately — the Sunset date is when the endpoint goes offline; the migration deadline is when you expect consumers to have migrated
• Use the API response header generator to produce Sunset and Deprecation header values per RFC 8594 — these signal deprecation in every response
• The consumer impact panel estimates which API versions are actively used — prioritize communication to consumers of high-volume deprecated endpoints

Fun Facts

• RFC 8594 'The Sunset HTTP Header Field' was published in 2019, but large API platforms like Twilio, Stripe, and Salesforce had been implementing custom deprecation headers since 2012-2015 — the RFC standardized existing practice rather than introducing it.
• Stripe maintains backward compatibility for each dated API version indefinitely — once you are on a version, it never breaks. This 'version pinning' strategy requires Stripe to maintain and test all historical API versions in production — an extraordinary engineering commitment.
• A 2021 SmartBear API survey found that 41% of API providers give less than 3 months' notice for breaking changes. Industry best practice recommends 6-12 months minimum for enterprise APIs with high adoption.

FAQ

What headers should I include in deprecated API responses?

Deprecation: true (or a date), Sunset: <HTTP date of removal>, and Link: <migration-docs-url>; rel=successor-version. These follow RFC 8594 and RFC 7231. Client libraries that check these headers can warn developers automatically.

How much notice should I give before removing an API endpoint?

Depends on your consumer base. Public APIs with external developers: 12+ months. Internal APIs between teams: 3-6 months. Emergency security-related deprecations: as much notice as risk allows — often 2-4 weeks with direct communication.

How do I know when it is safe to remove a deprecated endpoint?

Monitor traffic to the deprecated endpoint via access logs or API analytics. When traffic drops to zero (or to a pre-defined acceptable threshold), it is safe to remove. Never remove based on calendar date alone — always verify with usage data.