request-parameter-removed

What this check detects

A parameter was removed from an operation. This is reported as a warning rather than an error: a well-behaved client that simply stops sending it is usually fine, but some clients or API gateways reject a request that carries a now-undefined parameter, and any server behavior that was tied to it changes silently.

Deprecate a parameter before removing it, and confirm no client depends on its effect.

Example

The "sort" query parameter is gone. Clients still sending it get no sorting, and a strict gateway may reject the unexpected parameter.

Mitigation

This is a warning because some clients may return an error when receiving an unexpected parameter. It is recommended to deprecate the parameter first.

How to handle this change

When oasdiff flags request-parameter-removed, 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 request-parameter-removed 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
request-parameter-removed err

Then pass it to oasdiff:

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