api-removed-without-deprecation

What this check detects

Removing an operation (an HTTP method on a path) breaks every client that calls it: the request now returns 404 or 405 instead of the expected response. This check flags the case where the endpoint was deleted without first being deprecated.

The safe way to retire an endpoint is the deprecation flow: mark the operation `deprecated: true`, publish a sunset date, and remove it only after that date has passed, so clients have a window to migrate. Deleting it outright skips that window, which is why this is reported as breaking rather than as a managed removal.

Example

POST /users was removed with no prior deprecation. Clients that create users now get 405 Method Not Allowed.

How to handle this change

When oasdiff flags api-removed-without-deprecation, 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-removed-without-deprecation 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-removed-without-deprecation warn

Then pass it to oasdiff:

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