api-path-removed-without-deprecation

What this check detects

This check fires when an entire path is removed, taking all of its operations with it, without prior deprecation. Every client using any method on that path breaks at once.

It is the path-level counterpart of removing a single operation. Retire a path the same way: deprecate its operations, publish a sunset date, and remove after it passes.

Example

The whole /legacy-report path was removed with no deprecation, so every client calling it starts failing.

How to handle this change

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

Then pass it to oasdiff:

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