Sunset strategy

As explained in Automating API Delivery

Sunsetting is the process of making an API or endpoint unavailable in production after its deprecation period ends.

Sunsetting removes an API or endpoint from production after its deprecation window expires. Deprecation warns consumers and encourages migration; sunset makes the resource unavailable, typically producing a 404 Not Found response. Because removal is a breaking change, publish support durations and sunset dates so consumers can plan upgrades. section 4.11.3

A practical sunset workflow combines consumer notice with an explicit exception in automated breaking-change checks:

• Document the stable-version schedule and the length of API support, giving consumers time to test and migrate. section 4.11.3
• Mark the operation, parameter, or schema as deprecated with the OpenAPI deprecated field, then communicate the planned sunset date. section 4.11.3
• Remove the deprecated endpoint from the later API definition when the deprecation window closes. section 4.4
• Use Tufin/oasdiff to compare definitions and detect ordinary breaking changes; an unannounced path removal produces an error such as api-path-removed-without-deprecation. section 4.4
• Add an x-sunset date to the deprecated operation so oasdiff ignores endpoints whose sunset date has passed when checking planned removals. section 4.4

Sunsetting a catalog endpoint

A deprecated GET /v1/catalog/categories operation can be represented with deprecated: true and x-sunset: "2022-08-30". Compare the deprecated definition with the version that removes the path using oasdiff breaking apiv1-dep.yaml apiv2.yaml. The sunset marker lets the planned removal avoid failing the automated breaking-change check. section 4.4

Figure 4.7 API deprecation and sunset dates. After the deprecation date, an API isn’t recommended for use. But after the sunset date, the API is unavailable.

Timeline figure contrasting the deprecation date, when use is discouraged, with the sunset date, when the API becomes unavailable. section 4.11.3

How Automating API Delivery covers it

How deep it goes

Explains lifecycle timing, OpenAPI markers, oasdiff commands, and exception behavior, but stops short of implementation-server shutdown mechanics.

Examples

Uses GET /v1/catalog/categories, OpenAPI deprecated and x-sunset fields, and oasdiff comparison output.

What it assumes

Assumes familiarity with API definitions and CI/CD checks while teaching deprecation, sunset timing, and OpenAPI extension usage.

What you can do after

Configure planned endpoint removals with OpenAPI metadata and Tufin/oasdiff checks that distinguish sunsets from unannounced breaking changes.

How it connects

Connects API versioning, deprecation, OpenAPI, breaking changes, and CI/CD automation.

liveBookmanning.com

Read Automating API Delivery on liveBook Get the book at manning.com

Related concepts

• breaking changekind of · A breaking change is a modification to an interface, behavior, format, configuration, or contract that can prevent existing consumers from working correctly without changes.
• deprecationcontrasts with · Deprecation is the designation of a software feature, interface, component, version, or model as discouraged or no longer recommended while it remains available and may later be withdrawn.
• breaking change checkcontrasts with · A breaking change check detects changes between API versions that can cause existing consumers or implementations to stop working.

This explainer was generated by Manning's knowledge graph from the text of Automating API Delivery. The section links point to the parts of the book it draws on.