Sunsetting an API means retiring it permanently, often because it’s outdated,
replaced, or poses security risks. Without proper planning, this process can
disrupt users, harm trust, and lead to costly errors. Here’s how to handle it
effectively:

- **Plan a Clear Timeline**: Announce deprecation early (e.g., 6 months before
  shutdown). Set clear deadlines for migration and final removal.
- **Notify Users**: Use blog posts, emails, developer portal banners, and
  webinars to communicate the changes.
- **Support Critical Users**: Offer personalized help for key accounts and
  extend timelines if needed.
- **Use HTTP Headers**: Implement `Sunset`, `Deprecation`, and `Link` headers to
  notify users programmatically.
- **Schedule Brownouts**: Temporarily disable the API to test user readiness and
  gather feedback.
- **Return HTTP 410**: After shutdown, use the HTTP 410 status code to signal
  permanent removal, along with clear error messages and migration guides.

Properly managing
[API sunsetting](https://zuplo.com/blog/2024/10/24/deprecating-rest-apis)
ensures a smooth transition, minimizes disruptions, and maintains trust with
users.

## API Lifecycle Management: Deprecation and Sunsetting

Many of you might conflate the concepts of API deprecation and sunsetting.
Here's a video from our good friend, Erik Wilde, to explain the difference:

<YouTubeVideo videoId="twfufQn1mD0" />

tl;dw - Deprecation is the process of indicating that a given endpoint or API
should not be used anymore, whereas sunsetting is the process of making that
endpoint or API unusable. Deprecation precedes sunsetting. Check out our
[full guide to deprecating REST APIs](./2024-10-24-deprecating-rest-apis.md) to
learn more about API deprecation.

## How to Plan Your API Sunset Timeline

Creating a structured timeline is essential for a smooth API deprecation
process. It gives users enough time to migrate while ensuring a firm shutdown
date. A good plan combines clear deadlines, effective communication, and focused
support for critical users. This timeline sets the stage for implementing
technical deprecation signals and support strategies in later steps.

### Setting Important Dates and Deadlines

Your API sunset plan revolves around three key milestones: the
[deprecation announcement](https://zuplo.com/blog/2024/10/25/http-deprecation-header),
the migration period, and the final shutdown. Each milestone helps guide users
through the transition.

Announce the deprecation at least six months before the shutdown to give users
ample time to prepare. For instance, if you announce on March 15, 2025, you
might set a soft deadline for July 15, 2025, and finalize the shutdown on
September 15, 2025. This phased approach allows you to identify users who need
extra help and fine-tune your support efforts as the deadline nears.

Understanding API usage patterns and engaging directly with important clients
during this period is crucial.

The final shutdown date is when the API stops functioning entirely. Once
announced, this date should remain fixed to maintain user trust and ensure
effective planning. However, it’s wise to build in an internal buffer to handle
any unexpected issues.

### How to Notify API Users and Teams

Clear communication is vital during the sunsetting process. Start with a blog
post explaining the reasons for the deprecation, the timeline, and the migration
steps. Follow this with direct email notifications to all registered API users,
including both technical contacts and account managers.

Update your API documentation with clear deprecation warnings on affected
endpoints, and add banner notifications to your developer portal during the
sunset period. Hosting live webinars or Q&A sessions can also help clarify
migration requirements.

Ensure consistent messaging across all communication channels. Internally,
inform your customer success, support, and sales teams well in advance so
they’re prepared to handle user inquiries. Providing internal documentation that
explains the migration process in both technical and business terms can further
empower your teams.

Timing matters, too. Avoid making announcements during major holidays or busy
industry events to ensure your message gets the attention it deserves.

### Providing Extra Support for Mission-Critical Users

Once users are notified, focus on supporting those most impacted. Identify
mission-critical accounts based on factors like usage, revenue, or strategic
importance, and reach out to them individually before the public announcement.

Offer personalized support, such as dedicated channels, live chats, or
one-on-one consultations, to help these users transition smoothly. For those
with complex systems, consider extending the deprecation period on a
case-by-case basis. If you do, make sure the extension is time-limited and
clearly communicates the final migration deadline.

Set up a dedicated support channel specifically for sunset-related questions to
keep these inquiries separate from regular support requests. Training your
support team on the migration process ensures they can provide quick, effective
assistance without escalating every issue to engineering.

For large user bases, a phased or rolling shutdown can be helpful. Migrating
users in batches not only manages support workloads but also allows you to
adjust the process based on early feedback.

The goal is to ensure that your most important users feel supported throughout
the transition. A smooth migration experience reduces disruptions and can even
strengthen long-term relationships as users adopt your new API version.

## Using HTTP Headers to Signal API Deprecation

HTTP headers offer an automated way to notify client applications about API
deprecations. When used effectively, these headers ensure that all API
consumers - whether or not they read email updates or documentation - receive
deprecation notices and can plan accordingly. This approach works well alongside
other notification methods like timelines and direct client communication.

### How to Implement the Sunset Header

The **Sunset** header is designed to inform clients about the date when an API
endpoint will no longer be available. As outlined by the
[IETF](https://www.ietf.org/), this header specifies that a URI is expected to
become unresponsive after a particular date. To ensure compatibility across
systems, the date must follow the RFC 1123 format.

> "The Sunset HTTP header signals that a URI will become unresponsive at a
> specified future date." - IETF

Here’s an example of how to format the Sunset header:

```
Sunset: Sat, 25 Jul 2020 23:59:59 GMT
```

Include this header in every response from the deprecated endpoints. Consistency
is key - apply it universally across all affected responses. Additionally, make
sure to document the Sunset header in your API documentation so that clients can
detect and handle deprecation automatically.

### Adding Deprecation and Link Headers

To provide even more clarity, you can pair the **Sunset** header with additional
headers like **Deprecation** and **Link**. The
[Deprecation header](./2024-10-25-http-deprecation-header.md) explicitly marks
an API as deprecated, signaling to clients that the endpoint is on its way out.
Meanwhile, the Link header can point to a dedicated deprecation policy page that
explains why the change is happening and provides guidance for migration.

Here’s an example of how these headers might look together:

```
Deprecation: Sat, 1 Aug 2020 23:59:59 GMT
Link: <https://api.endpoint.com/deprecation>; rel="deprecation"; type="text/html"
```

When combined with the Sunset header, a complete response might look like this:

```
Deprecation: Sat, 1 Jul 2020 23:59:59 GMT
Sunset: Sat, 25 Aug 2020 23:59:59 GMT
Link: <https://api.endpoint.com/deprecation>; rel="deprecation"; type="text/html"
```

Make sure all dates align across your headers and other communications to avoid
confusion.

### Marking Deprecated and Sunset Endpoints in Documentation

As soon as you implement deprecation headers, update your API documentation to
reflect these changes. Clearly label each deprecated endpoint with its
deprecation and sunset dates, and include links to migration resources.

Provide a clear explanation for the deprecation - whether it’s due to security
upgrades, improved performance, or a shift in architecture. This helps users
understand the benefits of moving to the new solution. Additionally, create
detailed migration guides that walk users through the transition. Include
practical elements like code examples, parameter mappings, and troubleshooting
advice.

For major changes, you may also want to include deprecation warnings directly in
API responses. Just ensure these warnings don’t interfere with existing client
functionality.

Sunsetting is pretty controversial in the API space, with many companies never
actually shutting down old API endpoints out of principle. If you do plan on
shutting down an endpoint, provide specific reasons as to why the API cannot
continue operations.

## Using API Brownouts to Prepare Clients for Shutdown

API brownouts are a practical way to test how ready your clients are for an
upcoming shutdown. Unlike a permanent shutdown, these planned, temporary outages
allow you to see which integrations still rely on deprecated endpoints. They
also provide valuable insights to help you fine-tune your migration support.

The process is straightforward: you disable the deprecated features for a short
time - anywhere from a few minutes to a few hours - and then bring them back
online. During these outages, the API delivers clear error messages with
migration instructions, ensuring clients know what steps to take.

### How to Schedule and Announce Brownouts

Start by analyzing your API's usage patterns to find times when the deprecated
features are least active. Scheduling brownouts during off-peak hours - like
early mornings or late evenings based on your primary users' time zones - helps
minimize disruptions.

As the final shutdown date approaches, gradually increase the frequency and
duration of the brownouts. For instance, you could begin with 15-minute sessions
once a week, then move to 30-minute brownouts twice a week, and eventually
extend them to daily hour-long outages in the final weeks.

Communicate your
[brownout schedule](https://zuplo.com/docs/policies/brownout-inbound) well in
advance using multiple channels like email, developer portals, and API
documentation. Be specific with dates and times, using clear formats. For
example: **"Brownouts will occur on Tuesday, March 15, 2025, from 2:00 AM to
2:30 AM PST."**

Make sure your error messages during brownouts are clear and actionable. Instead
of generic error codes, provide detailed guidance, including links to migration
resources, alternative endpoints, and support contact information. Tools like
Zuplo's Brown Out Policy allow you to customize error responses to effectively
notify clients about what’s happening and what they need to do. Here's an
example on how to implement a brownout using Zuplo:

<YouTubeVideo videoId="_ISXtsCWLns" />

### What to Track During Brownout Periods

Monitoring brownouts gives you a wealth of information about your API’s
dependencies, helping you prepare for the final shutdown. Here are key areas to
focus on:

- **API Call Volume:** Keep track of requests hitting deprecated endpoints,
  broken down by client or company. This helps you identify who still relies on
  the old features and prioritize outreach.
- **Error Patterns:** Look for endpoints with high error rates and failing
  request types. These patterns can reveal which features clients are struggling
  to replace.
- **Service Dependencies:** Watch for failures in related services that depend
  on your deprecated API. These issues might not be obvious during normal
  operations but can surface during brownout testing.
- **Revenue Impact:** Assess potential revenue risks from clients who continue
  using deprecated features. This can help you decide whether to extend
  timelines for high-value customers or enhance migration support for them.

To make sense of this data, build detailed analytics dashboards. Segment the
information by client, endpoint, and time period to uncover patterns, like
clients repeatedly accessing deprecated endpoints without implementing proper
error handling or migration strategies.

### Using Brownout Data to Improve Migration Support

Brownouts often highlight migration challenges that standard deprecation
processes might miss. Use the insights you gather to make targeted improvements:

- **Support Struggling Clients:** Identify users who frequently encounter errors
  during brownouts and reach out with personalized support, leveraging your API
  analytics.
- **Revise Documentation:** If specific endpoints fail repeatedly, enhance your
  migration guides with detailed examples, troubleshooting tips, or alternative
  solutions.
- **Refine Error Messages:** If you notice a spike in support requests with
  similar questions, update your error messages to provide clearer, more
  specific instructions.
- **Adjust Timelines:** If key clients continue using deprecated features
  heavily, consider extending your sunset timeline or offering additional
  migration resources.
- **Target Specific Groups:** Use your data to identify clusters of users who
  still rely on deprecated features. Tailor your communication and support
  efforts to help these groups transition more effectively.

Brownout testing doesn’t just help with the current migration - it provides
valuable feedback for future API changes. If clients struggle with certain
aspects of your new API, you can use this information to make improvements,
ensuring a smoother process next time around.

## Implementing HTTP 410 for Final API Removal

When permanently retiring an API, using HTTP 410 responses is a crucial step.
This status code, unlike the more common 404 error, clearly signals that a
resource is gone for good. It helps developers understand the endpoint is no
longer available and prompts search engines to remove the URLs from their
indexes faster. Additionally, it discourages clients from continuing to make
requests to these endpoints, saving resources on both ends.

### Setting Up HTTP 410 Responses

To implement HTTP 410, update your server or application code to return this
status for all deprecated endpoints. The exact configuration will depend on your
specific infrastructure, but the process usually follows the same principles.

Start by identifying all endpoints slated for removal. Create a list of URL
patterns, methods, and routes that need to return the 410 status. Depending on
your setup, you might:

- Modify the `.htaccess` file for Apache servers.
- Adjust server configurations for NGINX.
- Use policy settings in your API gateway.

Here’s an example of a 410 response for a removed endpoint:

```http
HTTP/1.1 410 Gone
Content-Type: application/json
Date: Tue, March 15, 2025, 10:30:00 GMT

{
  "error": "This API endpoint has been permanently removed",
  "message": "The /v1/legacy-users endpoint was sunset on March 1, 2025",
  "migration_guide": "https://docs.yourapi.com/migration/v2-users",
  "support_contact": "api-support@yourcompany.com"
}
```

After configuring the responses, test each endpoint using HTTP checkers or
automated scripts to ensure they consistently return the 410 status. Verify that
your error messages are clear and follow a consistent format across all
endpoints.

### Writing Helpful Error Messages

A well-crafted error message can significantly ease the transition for
developers. While HTTP status codes provide technical details, they don’t always
offer enough context. Your error messages should include:

- The removal date of the endpoint.
- A brief explanation of why it was removed.
- Clear instructions for next steps, such as migration guides or support
  contacts.

By consistently structuring your error responses with fields for error type, a
human-readable message, migration resources, and support contact details, you
help developers handle these changes more effectively.

### Updating Documentation After API Removal

Once HTTP 410 responses are in place, promptly update your API documentation to
reflect the changes. Leaving outdated information in the documentation can
confuse developers and lead to unnecessary support requests.

Start by removing references to deprecated endpoints. Replace them with notices
about the removal, including the sunset date and migration details.

Consider creating a "Deprecated Endpoints" section in your documentation. List
all removed functionality along with their sunset dates, and include migration
guides with code samples in multiple programming languages. Update the[API
changelog or release notes to document the exact dates when 410 responses were
implemented, which endpoints were affected, and where developers can find
migration resources.

Additionally, review internal links and cross-references to ensure they no
longer point to removed endpoints. Update code examples, tutorials, and
quickstart guides to reflect current API versions. Prominent notices on your
developer portal about recent changes can also help keep developers informed,
especially if widely used endpoints are affected.

## Tools and Best Practices for API Sunsetting

Successfully retiring an API takes more than just sending HTTP status codes and
notifications. By combining effective tools with well-thought-out practices, you
can ease the transition for developers, maintain trust, and minimize the support
burden.

### Building Complete Migration Guides

A well-structured migration guide is essential for a smooth API sunset. It
should clearly compare the old and new endpoints, detailing the exact changes
developers need to implement. Include specifics about each endpoint's
functionality, the data they handle, and any dependencies - whether upstream or
downstream - that could impact the migration process. This level of clarity
helps you create realistic timelines and avoid surprises during the transition.

Break the migration process into manageable tasks with clear deadlines. To make
it even easier, provide side-by-side code examples that highlight the
differences between the old and new API calls. For instance, if you're
transitioning from `/v1/users` to `/v2/users`, include examples in widely-used
languages like JavaScript, Python, and cURL.

Keep everyone in the loop by regularly updating your documentation and
communicating the migration plan to both your internal team and external API
users. The guides should also address potential errors, explaining common HTTP
error codes and how to handle them. Highlight any new API features - like
filtering, sorting, or pagination - that improve performance. These detailed
resources set both your team and users up for success during the transition.

### Testing New API Versions Before Retirement

Thorough testing of the new API is a crucial step before retiring the old one.
Develop a testing strategy that ensures the replacement matches the original in
terms of functionality and performance. Use real-world scenarios to create test
cases with established frameworks, helping you quickly identify any issues.

To ensure a seamless transition, focus on backward compatibility and aim to
minimize downtime. Stick to best practices, such as using logical nesting for
endpoints, maintaining consistent naming conventions (like favoring nouns over
verbs), and implementing strong security and caching mechanisms. These steps not
only make the transition smoother but also provide a solid foundation for the
new API version.

### How Zuplo Simplifies API Sunsetting

Zuplo's API management platform offers tools that make the sunsetting process
much easier.

Zuplo is OpenAPI-native, which means you can directly document your sunset
headers or 410 responses in your spec. Not only will this ensure your
autogenerated developer docs are updated, but you can also enforce your APIs
actually send back these responses and headers at the gateway level (aka
[contract testing](./2025-04-01-guide-to-contract-testing-for-api-reliability.md)).

Zuplo has a fully programmable policy engine, which allows you to scale common,
custom building blocks like API brownout behavior, sunset responses, and more
across all of your sunset endpoints.

Beyond these capabilities, Zuplo offers robust tools for security, route
registration,
[schema validation](https://zuplo.com/examples/schema-validation-file-ref), and
authentication/authorization. This ensures consistent behavior across both
legacy and new API versions. With its analytics and monitoring features, Zuplo
provides valuable insights into usage patterns, helping you make informed
decisions about migration timelines and strategies.

## Conclusion: Your API Sunsetting Checklist

Sunsetting an API takes thoughtful planning, clear communication, and the right
tools. Rajat Malik from [Siemens](https://www.siemens.com/) highlights the
importance of transparency:

> "Effective management of API feature deprecation hinges on clear and timely
> communication with API consumers. Prioritize transparent communication by
> informing them about reasons, timelines, and alternatives for deprecated
> features, supplemented with comprehensive documentation and support." - Rajat
> Malik from Siemens

Start by mapping out a detailed timeline. Announce the deprecation well in
advance - ideally several months - while setting clear deadlines for each phase,
from the initial announcement to the final removal. Use a mix of communication
channels like emails, blog posts, and developer portals to ensure your message
reaches all stakeholders.

Incorporate **HTTP sunset headers** as soon as deprecation begins. These headers
provide machine-readable alerts to users. Follow up with direct emails to active
users of the deprecated endpoints, offering personalized support to help them
navigate the transition.

Keep an eye on API usage data through analytics. If you notice high usage
persisting, it might be time to revisit your communication strategy. Provide
clearer alternatives, refine your messaging, or even adjust your timeline if
necessary.

When the time comes for final removal, implement **HTTP 410 status codes** to
signal the change. Include helpful error messages that guide users toward
available alternatives. Update your documentation promptly to reflect the
changes, and maintain an open feedback loop to tackle any lingering issues.

Throughout the process, focus on **communication, consistency, and
collaboration.** Keeping open lines of communication with your customers and
partners not only eases the transition but can also uncover ways to improve your
API and strengthen relationships.

Ultimately, successful API sunsetting is a collaborative effort, not a
unilateral decision. Tools like Zuplo’s programmable policies and built-in
brownout support can help streamline the process while maintaining user trust.