The moment an API goes live, it’s no longer yours alone: the dealer portal, the mobile app, an ERP connector or a partner’s integration become tied to its current behavior. The typical failure in the field starts like this: a field is renamed as “a small fix”, the partner’s order transfer stops the same night and nobody finds the cause until morning. Versioning is the way to keep developing the API without breaking consumers unannounced: recognizing breaking changes, choosing the right versioning method and retiring the old version on a timeline.
The problem versioning solves
The API provider and the consumer work on different timelines. You want to rename a field; your partner’s development team may not touch that code for months. Versioning separates these two timelines: the new behavior is released in a new version, the old version keeps working unchanged for a set period, and the consumer migrates according to their own plan.
Versioning isn’t a goal; it’s a last resort. Every new major version means two code paths, two sets of documentation and two test suites maintained at the same time. The maintenance load doubles. That’s why the first goal is to make changes backward compatible wherever possible and release a new major version only when it’s unavoidable. If you’re still at the stage of choosing between REST and GraphQL, bear in mind that GraphQL approaches schema evolution differently; this comparison is in the REST or GraphQL guide.
Breaking and non-breaking changes
A breaking change is one that causes a correctly written existing client to stop working without any change on its side. Use the distinction below as a checklist in change reviews.
| Change | Class | Note |
|---|---|---|
| Adding a new optional field to a response | Not breaking* | The client should ignore unknown fields |
| Adding a new endpoint | Not breaking | — |
| Adding a new optional parameter to a request | Not breaking | Default behavior must not change |
| Deleting or renaming a field | Breaking | Add the new field first, announce the removal of the old one |
| Changing a field’s type (number → text) | Breaking | Strictly typed clients can’t parse it |
| Making an optional parameter required | Breaking | — |
| Adding a new value to an enum | It depends | Closed switch statements can break |
| Tightening a validation rule | Breaking | A request that passed yesterday gets a 422 today |
| Changing the default page size or sort order | Breaking | A behavior change is also breaking |
* Adding a new field being safe depends on consumers following the “ignore unknown fields” principle. State this expectation explicitly in your API documentation; clients that do strict schema validation may fail even on a new field. This is what breaks most often in the field: the provider says “we added a field, it’s not breaking”, and the class the consumer generated with a code generator throws an exception on the unknown field. Write non-breaking changes in the release notes too, so the consumer sees what changed.
The common way to make a breaking change without releasing a new major version is the expand and contract approach: the new field is added alongside the old one, both fields are populated together for a while, the old field is declared deprecated and removed when its usage drops to zero. It’s slow. But it doesn’t break anyone.
Versioning with the URI, a header or a parameter
| Method | Example | Advantage | Limitation |
|---|---|---|---|
| URI path | /v2/orders |
Visible, cache- and log-friendly, easy to route | The resource’s identity gets mixed with the version |
| Custom header | Api-Version: 2026-06-01 |
The URI stays fixed; suits fine-grained, date-based versioning | Less visible in the browser and in logs |
| Media type | Accept: application/vnd.example.v2+json |
Consistent with HTTP content negotiation | Client and tooling support can be weak |
| Query parameter | /orders?api-version=2 |
Simple, easy to try | Confusion in cache keys and signed URLs |
In most corporate web and integration projects, a major version in the URI path is a practical default: the partner understands it immediately, and it’s easy to tell apart in the proxy, WAF and log layers. In an incident review, looking at the access log and seeing which version was called in a single line saves a lot of time. Providers that release frequent, small changes may prefer date-based header versioning; for example, the GitHub REST API takes a date-format version with the X-GitHub-Api-Version header, and Stripe with the Stripe-Version header. Whichever method is chosen, three rules stay the same:
- The behavior of a request with no version must be documented (the oldest supported version or an error). An “always the latest” default defeats the purpose of versioning; on the day a new version is released, everyone who doesn’t specify a version breaks.
- Only major versions (breaking changes) should be visible to the consumer; minor and patch versions stay in the release notes.
- Events you send, such as webhook payloads, should be versioned too. Putting a schema version field in the event payload lets the receiver parse it safely; for the design of the receiving side, see the webhook receiver design guide.
Deprecation: the Deprecation and Sunset headers
The process of shutting down an old version or endpoint can be announced to the consumer with machine-readable signals. The Sunset header is defined in RFC 8594 and announces the date the resource will stop responding. The Deprecation header was standardized with RFC 9745 and carries the moment the resource was (or will be) deprecated as a structured date; the date is in Unix timestamp format starting with @.
HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://api.example.com/docs/v1-migration>; rel="deprecation"
In this example, @1798761600 corresponds to 1 January 2027 00:00 UTC; v1 is considered deprecated from this date and shuts down on 1 July 2027. The deprecation relation in the Link header gives the address of the migration document. The value of the headers comes from the client being able to log them automatically: an HTTP client layer that sees the header produces a warning, and the development team learns about the situation without reading documents.
The headers don’t replace an email and portal announcement; they complement it. Nobody reads response headers. But logs do. After the Sunset date, return a clear status code such as 410 (Gone) and an error body pointing to the migration document for requests to the old version; a silent 404 takes hours to diagnose.
Contract and change control with OpenAPI
Defining the API contract with an OpenAPI document moves breaking-change control from human attention to automation. OpenAPI supports the deprecated: true flag at the operation, parameter and schema level; documentation generators display this flag visually.
paths:
/v1/orders/{id}:
get:
deprecated: true
summary: Order detail (v1, use /v2/orders/{id} instead)
components:
schemas:
Order:
properties:
customerCode:
type: string
customer_code:
type: string
deprecated: true
When the contract file is kept in the same repository as the code, every change request can be compared with the previous version. The open-source oasdiff tool reports breaking changes between two OpenAPI documents; it can be run in the CI pipeline so that it stops the build on error-level findings:
oasdiff breaking openapi-main.yaml openapi-pr.yaml --fail-on ERR
Since the tool’s parameters can change between releases, check the documentation of the version you use. This check can be combined with the steps described in the CI/CD pipeline with GitHub Actions guide. It has a limit: automatic comparison can’t catch behavior changes (default sort order, validation logic, page size). The schema stays the same, the result changes. These need contract tests and a review checklist.
The migration process for integration partners
Once the technical mechanisms are ready, the process determines the success of the migration. When a new major version is released, follow this flow:
- Consumer inventory: Record which company, which application and which technical owner each API key or client ID belongs to. A timeline isn’t announced without knowing who will be affected. A key with an unknown owner is a surprise on shutdown day.
- Usage measurement per version: Report the number of requests per client and version from the access logs. This report shows the progress of the migration and whether the shutdown date is realistic.
- Announcement and timeline: Publish the deprecation and shutdown dates, the migration document and the change list at the same time. Set the period according to consumers’ development cycles and your contracts.
- Test environment: Open the new version early in a test environment where consumers can try it, with realistic sample data.
- Reminders and follow-up: As the shutdown date approaches, contact clients still using the old version directly.
- Planned brief outages (brownouts): Some providers disable the old version for short, pre-announced intervals before shutting it down; forgotten integrations become visible before shutdown day. Apply this method only with a clear announcement and at hours that won’t affect critical business flows.
- Shutdown and cleanup: After shutdown, remove the old code path, documentation and tests; otherwise versioning debt accumulates.
For setting up versioning and contract management for the business applications you develop and partner APIs, you can review the scope on our custom web application development and ERP, CRM and API integrations pages.
Frequently asked questions
Should the URI path or a header be preferred for API versioning?
For corporate partner integrations, a major version in the URI path is a practical default; it’s visible and easy to tell apart in log, proxy and WAF layers. For APIs that release frequent small changes and want fine-grained, date-based versioning, header-based versioning is more flexible. Whichever is chosen, the behavior of an unversioned request must be documented.
Is adding a new field to a response a breaking change?
Not in the generally accepted approach; but that depends on consumers ignoring unknown fields. Clients that do strict schema validation may fail on a new field. State explicitly in the API documentation that unknown fields must be ignored, and announce new fields in the release notes.
What’s the difference between the Deprecation and Sunset headers?
The Deprecation header announces the moment the resource was deprecated; the resource keeps working but shouldn’t be used in new development. The Sunset header announces the date the resource will stop responding. Used together, the consumer receives both the warning and the deadline in a machine-readable form.
How long should an old API version be supported?
There’s no single right period. It’s determined by consumers’ development cycles, contracts with partners and the size of the change. The decision should be based on measuring usage per version, and the timeline should be announced in writing when the new version is released.