When an API changes, consumers need to know whether calls they already make will still work. An endpoint is identified in these checks by its HTTP method and path, such as GET /v1/catalog/categories. Removing that path means existing callers receive a 404 Not Found response; changing an endpoint’s description does not have the same effect on their code. section 4.3 section 4.4
Compare OpenAPI definitions before deciding how to release a change. Run `oasdiff diff api.yaml apiv2.yaml` to inspect additions, deletions, and modifications. The report places changed paths under those headings and can drill into an operation’s description, responses, and headers. A diff tells you what changed; a breaking-change check asks whether consumers must change their code. section 4.3 section 4.4
paths:
deleted: #1
- /v1/catalog/categories
modified:
/v1/catalog/products:
operations:
modified:
GET:
description: #2
from: List all products.
to: List all products in Acme's catalog.
responses:
modified:
"200":
headers: #3
added:
- x-rate-limit-hour
- x-rate-limit-remaining
…
components:
schemas:
deleted: #1
- CategoriesResponse
The YAML diff separates the deleted categories path from the modified products GET operation. It also shows that the products change includes a description edit and added response headers. section 4.3
Run `oasdiff breaking api.yaml apiv2.yaml` to check compatibility. Removing GET /v1/catalog/categories without deprecation produces an `api-path-removed-without-deprecation` error. JSON output is also available with `--format json`. Treat sunsetting separately in your release policy: an endpoint removed after a notified deprecation window is still a breaking change, but you may not want that planned removal to fail the automated check. section 4.4
Record endpoint additions, deprecations, and removals in an API changelog so consumers can plan updates. `oasdiff changelog api.yaml apiv2.yaml` can supply a starting list of changes; edit and format it for the people who use the API. section 4.5
