API Deprecation and Sunset Guidelines

Overview

During the lifecycle of an API, it may become necessary to phase out an API endpoint, an API version, or a specific API feature.

Typical examples include:

• Removing an unsupported field or parameter
• Replacing an API endpoint with a new design
• Shutting down obsolete business functionality

As long as existing consumers are still using these APIs or features, removing them is considered a breaking change and must not happen without proper communication and migration processes.

To ensure that API consumers have sufficient time to adapt, API providers should define and communicate:

• Deprecation date
• Sunset date

The deprecation and sunset process should be communicated primarily through standard communication channels, such as:

• API documentation
• Release notes
• Service agreements
• Customer notifications

HTTP headers and API specifications should be considered additional technical communication mechanisms, not the only notification method.

Deprecation vs Sunset

Deprecation

A deprecation date defines the point in time after which an API feature enters a limited-support phase.

After deprecation:

• The API feature remains available.
• Existing clients can continue using it without immediate changes.
• No new functionality will be added.
• The feature should no longer be used for new integrations.
• Consumers should start migration planning.

Deprecation itself is not a backward-incompatible change.

Example:

Deprecation date: 2026-01-01

The API remains functional, but users are expected to migrate to the replacement API.

Sunset

A sunset date defines the point in time when an API feature will be permanently removed.

After sunset:

• The API endpoint or feature is no longer available.
• Existing clients using the removed functionality will fail.
• Consumers must have completed migration before this date.

Sunset is a breaking change.

Example:

Sunset date: 2027-01-01

The API endpoint will no longer be accessible after this date.

The period between deprecation and sunset must provide sufficient time for consumers to migrate.

Deprecation Lifecycle

Phase 1: API Feature Deprecation

Example:

Deprecation date: 2026-12-31

Required actions:

• Mark the API feature as deprecated in the API specification.
• Document replacement APIs or migration approaches if available.
• Start returning the Deprecation HTTP header.

Example:

Deprecation: Thu, 31 Dec 2026 23:59:59 GMT

Phase 2: Announce API Sunset

Example:

Sunset date: 2027-12-31

Required actions:

• Document the sunset date in the API specification.
• Start returning the Sunset HTTP header.
• Continue returning the Deprecation header.

Example:

Deprecation: Thu, 31 Dec 2026 23:59:59 GMT
Sunset: Fri, 31 Dec 2027 23:59:59 GMT

Phase 3: Remove API Feature

At the sunset date:

Required actions:

• Remove the deprecated resource from the API specification.
• Reject requests targeting the removed resource.

Recommended HTTP response:

HTTP/1.1 410 Gone

The 410 Gone status indicates that the resource existed previously but is permanently unavailable.

Partner Agreement for Deprecation Period

When an API is consumed by external partners, the API provider must define a reasonable maintenance period after announcing deprecation.

External consumers should agree on:

• The minimum supported period after deprecation.
• The expected migration timeline.
• The sunset schedule.

This agreement should happen before consumers start using the API.

The goal is to ensure that consumers have enough time to migrate before the API becomes unavailable.

Reflect Deprecation in OpenAPI Specification

API deprecation information must be included in the OpenAPI specification.

The following API elements may be deprecated:

• API endpoints
• Operations
• Parameters
• Request/response schemas
• Schema properties

The affected element should use:

deprecated: true

Example:

paths:
  /customers:
    get:
      deprecated: true
      description: >
        This endpoint is deprecated.
        Use /customer-profiles instead.

Additional documentation should explain:

• Why the feature is deprecated.
• What replacement should be used.
• How consumers should migrate.
• Planned sunset date.

Example:

description: >
  This field is deprecated.
  Use "customerName" instead.
  This field will be removed after 2027-01-01.

Deprecation and Sunset HTTP Headers

During the deprecation period, API providers should include deprecation information in HTTP responses.

Recommended headers:

Deprecation: <date-time>
Sunset: <date-time>

Example:

HTTP/1.1 200 OK

Deprecation: Thu, 31 Dec 2026 23:59:59 GMT
Sunset: Fri, 31 Dec 2027 23:59:59 GMT

Deprecation Header

The Deprecation header indicates that an API feature is no longer recommended for new usage.

It may contain:

• A timestamp indicating when deprecation starts.
• A boolean value indicating that a feature is already retired.

Example:

Deprecation: Thu, 31 Dec 2026 23:59:59 GMT

Sunset Header

The Sunset header indicates the final date when the API feature will stop being available.

Example:

Sunset: Fri, 31 Dec 2027 23:59:59 GMT

The sunset date should provide enough time for consumers to migrate to the replacement solution.

Multiple Deprecated Features

If multiple API elements are deprecated in the same response, the headers should represent the earliest relevant date.

Example:

Feature A sunset:
2027-12-31

Feature B sunset:
2027-06-30

The response should use:

Sunset: Wed, 30 Jun 2027 23:59:59 GMT

because it represents the shortest migration window.

Client Monitoring Recommendations

API consumers should monitor deprecation-related information.

Recommended practices:

• Monitor Deprecation headers.
• Monitor Sunset headers.
• Create alerts for upcoming API removals.
• Plan migration activities before sunset dates.

Example:

If Sunset date is within 90 days:

→ Notify API owners
→ Start migration activities
→ Track migration progress

Important Notes

Headers Are Not a Replacement for Communication

The presence of:

Deprecation
Sunset

headers alone does not replace proper communication with API consumers.

API providers should also use:

• API documentation
• Release notes
• Migration guides
• Customer communication channels

Avoid Using Warning Header

Some systems historically used the HTTP Warning header for deprecation notifications.

However:

• Its semantics are less specific.
• It has limited suitability for API lifecycle management.
• Modern API lifecycle management should use dedicated Deprecation and Sunset headers.

Summary

A well-managed API retirement process should follow these principles:

A clear deprecation and sunset strategy enables API evolution while minimizing disruption for consumers.