A breaking change modifies an API incompatibly enough to force consumers to change client code. Existing applications may stop communicating with the server or suffer degraded service; removing an endpoint can produce a 404 Not Found response. section 4.4 section 4.6
Treat compatibility as a consumer constraint during API evolution. Additive changes generally let consumers extend their clients later, while breaking changes usually require a new API version or coordination with every affected consumer. section 4.6 section 4.11.1
Define and publish an organization-specific policy before automating checks. Typical breaking changes include:
- Deleting an endpoint or adding a required path parameter. section 4.11.1
- Adding required request properties or headers, or making optional request data mandatory. section 4.11.1
- Adding validation constraints, reducing array capacity or string length, or deleting an enum value. section 4.11.1
- Classifying a new response enum value requires an explicit policy: some organizations treat it as breaking, while others treat it as nonbreaking. section 4.11.1
Detect a removed endpoint with oasdiff
Compare the original and changed OpenAPI definitions with `oasdiff breaking api.yaml apiv2.yaml`. A result such as `api-path-removed-without-deprecation` identifies the removed `GET /v1/catalog/categories` operation as a breaking change. Use `--format json` when pipeline processing needs structured output. If the endpoint was deliberately sunset after deprecation, compare the deprecated definition with the final definition and decide whether the policy should allow that planned removal. section 4.4
Table 4.1 Examples of breaking changes to an OpenAPI definition file
|
API object
|
Category of change made
|
Change details
|
|---|---|---|
| Path |
Deleting Adding |
Deleting an endpoint Adding a new required path parameter |
| Request |
Adding/increasing | Adding a new required property in the request body Adding a new, validated pattern to a request schema Adding a new required header parameter Increasing the minimum number of items in an array in the request |
| Changing | Changing a request header parameter from optional to mandatory Changing an optional property in a request body to mandatory Changing a validated pattern in a request parameter |
|
| Deleting/reducing |
Deleting an enum value Reducing the max number of items in an array in the request Reducing the max length of a string |
|
| Response |
Adding/Increasing |
Increasing the max length of an array in a response Adding a new enum value (potentially breaking depending on client code implementation) |
| Changing |
Changing a required property in the response body to optional Changing an existing response header from required to optional |
|
| Deleting/reducing |
Deleting a required property Deleting a media-type from a response Deleting an enum value. Deleting a required response header Reducing the min number of items in an array in a response Reducing the min length of a string in a response |
Browse representative OpenAPI definition changes classified as breaking, including path deletion, newly required request data, tighter validation, reduced limits, and enum changes. section 4.11.1
Deprecation notifies consumers that an API or endpoint will be removed; sunsetting makes it unavailable after the deprecation window. Treat planned sunset as a policy case rather than assuming every automated failure should block delivery. section 4.4
