api-path-removed-before-sunset

Path and endpoint deleted before sunset date.

areapathskindexistenceactionremove

Breaking change (level: error)

It removes an endpoint or operation clients were using, so calls to it will fail.

What this check detects

OpenAPI lets you retire an endpoint gracefully instead of deleting it outright. You first mark the operation deprecated: true, which is not itself a breaking change: it only signals an intent to remove. oasdiff also reads an x-sunset extension, an RFC 3339 date that announces when the endpoint will actually be removed, so clients know how long they have to migrate.

This check fires when a path and its operations are deleted before that announced sunset date has passed, that is, earlier than clients were told to expect. Removing the path on or after its sunset date is allowed and is not reported; removing it early breaks clients that were still relying on the promised window.

Example

Before
After
1paths:1paths:
2 /v1/users:
3 get:
4 deprecated: true
5 x-sunset: '2027-01-01'
6 responses:
7 '200':
8 description: OK
9 /v1/health:2 /v1/health:
10 get:3 get:
11 responses:4 responses:
12 '200':5 '200':
13 description: OK6 description: OK

/v1/users was removed while its announced sunset date (2027-01-01) was still in the future. Removing it on or after the sunset date would not be reported.

How to handle this change

When oasdiff flags api-path-removed-before-sunset, you have a few ways to respond:

  • Find a backward-compatible alternative. Redesign the change so clients that followed the old contract keep working, and agree on the approach with whoever introduced it.
  • Release it in a new API version. Keep the current contract and introduce the change in a new version, then deprecate the old one with a sunset date so clients have time to migrate.
  • Accept it as a deliberate breaking change. Sometimes a breaking change is unavoidable, such as an urgent or security fix. Approve it knowingly, document it in your release notes, and tell affected clients. This should be the exception, not a routine way of working.

If oasdiff's verdict does not match your API's compatibility policy, you can also change how it treats api-path-removed-before-sunset with a severity-levels file:

Put one rule per line; the level can be err, warn, or info, or none to disable the check entirely:

# severity.txt
api-path-removed-before-sunset warn

Then pass it to oasdiff:

oasdiff changelog base.yaml revision.yaml --severity-levels severity.txt

Related paths rules

Browse all 509 checks →