Contents
Purpose and importance of API deprecation
API deprecation, the act of marking a part of an API as no longer recommended, is very important for several reasons:
– Advance notice & planning: It gives developers enough time to update their applications. This prevents sudden problems and avoids breaking things during important production times.
– Maintain trust & transparency: Being clear about changes builds trust with the developers who use your API. It helps keep a good relationship because they know what’s happening and can plan accordingly.
– Reduce technical debt and security risks: By deprecating old APIs, teams can remove code and systems that are insecure, hard to maintain, or inefficient. This helps keep the API healthier and more secure.
Key terminology
When we talk about APIs changing, two important terms are “deprecation” and “sunsetting.”
Deprecation vs. Sunsetting (Retirement)
– Deprecation: This is when a specific part of an API, like a particular web address (endpoint), a type of data, a data field, or a whole version of the API is formally announced as no longer recommended for use. It still works, but it’s a clear signal to users to switch to a newer solution sooner rather than later. This phase is designed to make transitions smooth without immediately breaking anything.
– Sunsetting (also known as retirement or decommissioning): This is the final stage when the API or resource becomes completely unavailable. After the “sunset date,” if a client tries to use it, they will get errors (like HTTP 4xx or 3xx status codes) or find that the endpoint simply doesn’t work anymore.
Deprecation / Sunset HTTP headers
APIs can use special standard HTTP headers to tell clients about these lifecycle stages in a way that computers can understand:
– Deprecation header (per IETF draft): This header is used while the resource is still active but is being discouraged. It tells you the date when the resource was deprecated (or will be in the future). When clients see this, they should avoid building new things that rely on it.
– Sunset Header (RFC 8594): This header indicates the specific date when the resource is expected to become completely unavailable. This header is only used during the “sunsetting” phase, not during deprecation.
Together, these headers can provide a machine-readable timeline:
Deprecation: @1688169599 Sunset: Wed, 30 Jun 2024 23:59:59 GMT Link: <https://developer.example.com/deprecation>; rel="deprecation"
The Link header with rel=”deprecation” can point clients directly to detailed documentation that explains the deprecation timeline, the reasons for it, and instructions on how to migrate.
Link relation type: deprecation
This is a specific value used in the HTTP Link header (e.g., Link: <URL>; rel=”deprecation”). It tells clients that the linked URL provides information or policies about the deprecation, including the timeline, the reasons, and migration instructions. This helps standardise how clients find deprecation information without having to guess.
Scope of deprecation
Deprecation might apply in different ways:
– To a single endpoint.
– To an entire API resource.
– To multiple endpoints at once.
Some APIs might only show deprecation headers in a central place (like their main documentation page), suggesting the changes apply broadly. Clients shouldn’t assume uniform coverage, so the API’s documentation needs to clearly explain the exact scope of the deprecation.
Grace period (Transition window)
The “grace period” or “transition window” is the time between when a deprecation notice is given and the final sunset deadline. This crucial period gives developers time to update their systems without causing problems in their live applications. Industry standards often suggest grace periods that last several months; for example, some companies provide 3–6 months for sunsetting, followed by up to 12 months of critical support for deprecated features.
When to issue a deprecation notice
Rationale: Why & when to begin deprecation
Decisions to deprecate an API usually come from one or more of these reasons:
– New version launch: If you have a newer, better-designed version of your API available, it’s time to start phasing out the old one.
– Technical debt: Older parts of your code (maybe using outdated frameworks or insecure components) become hard to manage and keep up-to-date. Deprecating these older APIs helps reduce the ongoing work needed to maintain them.
– Security concerns: If a version of your API has security flaws or no longer meets current security standards, it’s essential to plan for its deprecation.
– Low usage: When your data shows that very few people are using a particular API version, the cost of maintaining it might no longer be worth it.
– Strategic shifts: Changes in your business goals, combining services, or making big architectural changes (like moving from REST to GraphQL or using microservices) can make it necessary to deprecate older APIs.
Timing & duration recommendations
Advance notice
– Typical duration: 3–6 months (or longer for complex users)
– Notes: Industry guidelines usually suggest a grace period of at least 3–8 months. For very important APIs, some organisations offer up to 12 months to give users plenty of time to adapt.
Sunset deadline
– Typical duration: Clearly defined final date
– Notes: Always include a clear date when the API will be completely removed (e.g., “2025-12-15”) in all communications and HTTP headers.
Phased tapering
– Typical duration: Gradual reduction of support.
– Notes: Start by just marking APIs as ‘deprecated’ while they still fully work. Then, gradually reduce support or features until they are finally switched off.
Stakeholder considerations
The timing and communication of deprecation also depend on who uses your API:
User adoption levels
– High-usage APIs: These need longer timelines and more active communication (like special emails, webinars, or dedicated support) because many users will be affected.
– Low-usage APIs: You can use automated notifications, shorter grace periods, and provide less intensive support.
Enterprise or strategic accounts
For very important business clients, consider offering personalised extensions to the deprecation period or planning staggered (spread-out) sunsets to avoid disrupting their critical operations.
How to structure a deprecation notice
When an API feature is going away, how you tell users about it is key. Here’s a structured way to do it:
Announcement & communication strategy
– First public notice: Send out a full announcement as early as possible. This should be a blog post, a banner on your developer website, an email, or an entry in your changelog. It needs to explain why the API is being removed, the timeline (when the notice was given, and the final date it will stop working), and how to switch to the new way. Being open here builds trust with developers.
– Reach out to active users: Find your biggest users or business clients and contact them directly (via email or their account manager) to offer specific help with migrating. For users you don’t know well, check your access logs and try to notify relevant companies or internet providers.
– Regular reminders: Send at least one reminder halfway through the transition period, and then a final alert close to the date it will stop working. Use many ways to send these reminders, like banners on your website, newsletters, and warnings inside the API itself.
Documentation signals & visual indicators
– Mark in docs: Clearly label deprecated endpoints or versions in your API documentation and specifications (e.g., in OpenAPI, set /deprecated: true). This immediately tells developers the status.
– Visual warnings: Display clear visual warnings, like a yellow banner at the top of your documentation page, in any deprecated areas. Make sure these warnings link clearly to guides on how to switch to the new API.
Technical implementation via HTTP signals
Deprecation & sunset headers
– Use the Deprecation header (with a timestamp or date) during the deprecation and transition period. This tells clients the feature is being phased out.
– When it’s time for the API to truly stop working, start including the Sunset header (following RFC 8594). This header explicitly states the date when the API will become unavailable.
Link relation headers
Add Link headers like Link: <…>; rel=”deprecation” or rel=”sunset”. These links guide clients directly to documentation that covers how to migrate and when the API will be removed.
Warning headers (optional)
Some providers also use the general HTTP Warning: 299 – “Deprecated API…” header to flag each request. While not a standard for API deprecation, it can be an extra signal alongside the main headers.
Migration guidance & support
– Migration guide content: Offer a clear, step-by-step guide. This should include how old endpoints map to new ones, code examples for switching, frequently asked questions, and troubleshooting tips.
– Support channels: Provide help through developer forums, help desk tickets, in-app contact forms, or even dedicated teams for big clients who need extra migration support.
Pitfalls to avoid in API deprecation
Even when you mean well, deprecating an API can go wrong without careful planning. These mistakes can frustrate users and break trust. Here are common pitfalls and how to avoid them:
Not enough notice or grace period
– Mistake: Announcing that an API will be removed with too little warning, or giving users too short a time to switch. This can disrupt their operations and damage trust.
– Avoidance: Industry best practices recommend giving at least 3–6 months’ notice, or even up to 12 months for very important APIs or for large companies that depend on your API. Not communicating early enough means developers have to rush, which can lead to mistakes or service outages.
Poor or missing guidance
– Mistake: Announcing a deprecation but not providing clear instructions on how to switch to the new version (e.g., no code examples, no explanations of how old parts map to new ones, no FAQs). Many users will be left stranded.
– Avoidance: Always provide detailed migration guides, including code samples and common questions.
Ignoring monitoring & feedback
– Mistake: Not using analytics and monitoring tools to see how deprecation is going. This creates blind spots: you won’t know if old APIs are still being used, how quickly users are switching, or if there are problems during migration.
– Avoidance: Use tools that can track how often deprecated endpoints are being used. This helps you understand who is still relying on the old API and if they’re having trouble switching.
Removing APIs too abruptly
– Mistake: Going straight from deprecation to completely shutting down an API without a planned transition (like “brown-outs,” where you briefly turn it off to see who complains, or gradually reducing support). This can alienate users and erode trust.
– Avoidance: Consider strategies like temporarily disabling deprecated features to identify inactive users before a full shutdown.
Poor communication cadence
– Mistake: Sending only one notice about deprecation and no reminders. This often means users miss the deadlines.
– Avoidance: Use multiple communication channels (emails, developer portal announcements, banners, newsletters) and send periodic reminders throughout the grace period, especially nearing the final sunset date, to ensure all users are aware.
Lack of post-mortem review
– Mistake: Not looking back to analyse what happened after an API is removed. This prevents you from learning valuable lessons.
– Avoidance: After an API is sunset, review how clear your communication was, how many users successfully migrated, how effective your support was, and any wider impact on the ecosystem.
Neglecting ecosystem impact
– Mistake: Especially for widely used APIs, not considering that deprecations can affect many other things that depend on your API, such as SDKs, third-party libraries, or other integrations.
– Avoidance: Understand your API’s ecosystem. Plan and communicate with partners who build tools or integrations on top of your API to help them update their systems.
Sportmonks as a real-world example of API deprecation
Sportmonks effectively shows how to handle API deprecation well:
– Clear marking: Our Football API v2 is clearly labelled as deprecated. All our documentation points developers to switch to the newer v3.
– Ample notice: Our API v2 will continue working until at least the end of 2025. Users are also promised a “clear notification” about the exact end date of support, giving them plenty of warning and time to adapt.
– Dedicated migration path: Sportmonks provides clear instructions in their documentation about the differences between v2 and v3, showing how old parts of the API map to new ones, and outlining what to expect regarding timelines.
Plan ahead with Sportmonks’ API roadmap
With Sportmonks, API deprecation isn’t a surprise, it’s a well-communicated step in your growth. We give you clear timelines, helpful migration docs, and long support windows so you can evolve without disruption.
Stay future-ready and build confidently with Sportmonks today.
Faqs about deprecation notice
