API Versioning Strategies: How to Stop Breaking Changes When AI Writes the Code

API versioning lets a team change an API without breaking the services and clients that depend on it. Coding agents now write much of that change, and a version bump only happens when someone notices the change is breaking. The guide covers API versioning strategies, the best practices that make a versioning policy hold, and how teams catch breaking changes across repositories before they merge, whether a platform team owns many services or a high-velocity team ships agent code every day.

What Is API Versioning?

API versioning is the practice of changing an API’s contract so existing consumers keep working, and of labelling each change so consumers know when they must act. A version number is a promise to every consumer, and the promise only means something if the number moves when the contract breaks.

API versioning scheme vs API versioning strategy

An API versioning scheme decides how versions are numbered: semantic versions, dates or simple integers. An API versioning strategy decides where the client states the version: in the URL, a query parameter, a header, the media type or an account setting. Many guides mix the two, but a team can pair any scheme with any strategy, such as dated versions sent in a header.

Semantic versioning for APIs

Semantic versioning (semver) uses three numbers, MAJOR.MINOR.PATCH. MAJOR goes up for incompatible API changes, MINOR for backward compatible functionality and PATCH for backward compatible bug fixes. Public HTTP APIs usually expose only the major number, as in /v1/.

When an API change needs no new version

An additive change needs no new version: a new optional field, a new endpoint or a new optional parameter leaves every existing client working. An internal rewrite behind an unchanged contract needs none either.

What Counts as a Breaking Change in an API

A breaking change is any change that makes a correct client fail or misread data. Most breaking changes are ordinary edits:

1. A removed endpoint. The client gets a 404 where a route used to be.
2. A removed or renamed response field. The client reads a null value.
3. A changed type. A string becomes a number, or an object becomes a list.
4. A new required input. Old requests now fail validation.

A behavioral break keeps the same shape and changes the meaning, such as an amount switching from cents to whole units. No schema diff sees a behavioral break, so a reviewer has to read the code that uses the field.

Version numbers rarely warn consumers about any of these. 66.8% of the public API contracts that changed over three years (161 of 241) contained at least one breaking change, according to the Routebase study, which compared OpenAPI specs fetched in September 2026 with copies saved in spring 2023. The study covers only public APIs listed in the apis.guru directory, so internal APIs are not counted.

API Versioning Strategies Compared

REST API versioning comes down to five strategies, and each one trades discoverability, caching and client effort:

1. URL path versioning
2. Query parameter versioning
3. Header versioning
4. Media type versioning
5. Date-based version pinning

URL path versioning

URL path versioning puts the major version in the path, such as /v1/orders. The version shows in every log line, caches treat each version separately and gateways route by prefix, but a new major version means a new URL tree.

Query parameter versioning

Query parameter versioning adds the version to the query string, such as ?version=2. The approach is quick to add to an existing API, but clients can leave the parameter out, so the API needs a documented default.

Header versioning

Header versioning sends the version in a custom header such as Api-Version: 2. URLs stay clean and stable, but testing in a browser gets harder, and caches need a Vary header so they do not serve one version’s response to another version’s client.

Media type versioning

Media type versioning puts the version in the Accept header, such as application/vnd.example.v2+json. Each representation gets its own version, which sits closest to REST semantics, but clients carry the most effort.

Date-based version pinning

Date-based version pinning ties each account or client to the API version it first used, and new behavior ships as dated versions. The strategy suits public APIs with many integrators who upgrade on their own schedule, at the cost of running many versions at once.

gRPC versioning and GraphQL versioning

For gRPC versioning, protobuf packages carry the version, such as orders.v1 and orders.v2. Buf’s buf breaking command checks a schema against an earlier version with four rule categories, from strictest to most lenient: FILE, PACKAGE, WIRE_JSON and WIRE.

GraphQL versioning usually means no versions at all. GraphQL schemas evolve by adding fields and marking old ones with @deprecated, so clients move at their own pace and the server keeps old fields until usage drops.

API Versioning Best Practices

A versioning policy is only as strong as the check that enforces it on each change. Six API versioning best practices make the policy hold:

1. Prefer additive, backward compatible changes
2. Write the API versioning policy down
3. Announce API deprecation in the response
4. Know every API consumer, internal ones too
5. Keep one API spec as the source of truth
6. Automate API compatibility checks at every layer

Prefer additive, backward compatible changes

Backward compatibility is cheapest when every change adds rather than replaces. Add new fields and endpoints, keep old ones working, and never give an existing field a new meaning.

Write the API versioning policy down

A written API versioning policy says what counts as breaking, how long a deprecated version lives and who approves a new major version. Version the contract rather than the implementation, so internal refactors never force a version bump.

Announce API deprecation in the response

The Deprecation header defined in RFC 9745 tells clients a resource is deprecated, and the Sunset header from RFC 8594 gives the removal date. Pair both headers with a migration guide, so API deprecation reaches the developer who has to change the client.

Know every API consumer, internal ones too

Public API consumers are usually tracked by API key, but internal consumers in other repositories are not, and many internal APIs were agreed in a meeting and never written into a spec, so nobody knows who reads a field until the field disappears.

Keep one API spec as the source of truth

Generate the OpenAPI or protobuf file from the code, or validate the file against the code in CI. Compatibility checks can only compare the contract they are given, so a stale spec hides real changes.

Automate API compatibility checks at every layer

Each layer of compatibility checking reads something different:

• Spec diff. oasdiff compares two OpenAPI versions and lists breaking changes, and buf breaking does the same for protobuf.
• Consumer contract tests. Pact runs consumer-written interaction tests against the provider, and the Pact Broker’s can-i-deploy check says whether a version is safe to release.
• Code review across repositories. A reviewer that reads consumer code in other repositories on every PR covers consumers that have no spec or contract tests.

Spec diffs and contract tests check the contract a team wrote down. Cross-repo code review checks the code that uses the contract.

When to Use a Spec Diff, Contract Tests or Cross-Repo Code Review

A spec diff suits any API with a maintained OpenAPI or protobuf file. A spec diff is cheap to run in CI on every PR and catches removed fields and changed types, but sees nothing the spec leaves out.

Contract tests suit APIs whose consumers will write and keep interaction tests. Contract tests prove that recorded interactions still pass, but only for consumers that wrote tests.

Cross-repo code review suits organizations with internal consumers spread across repositories, informal APIs and behavioral changes that no schema shows. Enterprise engineering teams usually need the spec diff for speed, contract tests for the consumers who own them, and cross-repo review for everyone else. High-velocity teams often start with the spec diff in CI and cross-repo review on every PR, because neither asks consumers to write tests.

Why AI-Written Code Breaks API Contracts Without a Version Bump

The version bump depends on someone noticing the change is breaking, and with coding agents neither the author nor the diff sees the consumers in other repositories. Four failure modes repeat:

1. The agent edits one repository. The coding agent renames a field, updates the producer’s tests and gets a green build, while the consumer that reads the old field sits in another repository.
2. The diff hides the dependents. Diff-only review shows what changed, not who depends on it. 18.7% of engineering leaders said AI review tools still miss context-specific or architectural violations, according to the Qodo State of AI Code Quality 2026.
3. A person types the version number. A contract changes whenever the code changes, but a version number changes only when someone decides the change is breaking.
4. Internal contracts were never written down. Spec-based checks cannot see an API that has no spec.

Review that ships with a coding assistant, such as GitHub Copilot code review, reads its context from the pull request’s own repository plus any Model Context Protocol (MCP) servers the team configures. Qodo’s walk-through of how breaking changes propagate traces the path from one edit to a broken consumer in detail.

Where API Versioning Broke Down: 3 Examples

The three examples below are illustrative composites based on patterns from customer calls. No real company, figure or quote is used.

API versioning example 1: a contract change followed by another team’s PR

A team changed an event contract in one repository, and the change merged cleanly. Within the hour, another team opened a PR in a different repository that still wrote the old event shape.

Qodo’s cross-repository review read the related repository when the second PR opened and raised a Cross-repo conflict finding linked to the changed contract. The second team updated its producer before merge.

API versioning example 2: internal APIs agreed in a meeting

An engineering organization had dozens of internal API calls that teams had agreed on informally and never documented. Spec diffs could not help, because no spec existed, and a renamed field broke a reporting service owned by another group.

Qodo’s automatic cross-repo discovery inferred the service relationships from the code itself, so the next rename raised a finding that pointed to the reporting service’s lines.

API versioning example 3: a weekly manual sweep before refactors

An engineering group ran a week-long manual sweep of consumers before every major refactor. Smaller changes shipped with no consumer check at all.

Qodo replaced the sweep with a check on every PR: each change to a shared endpoint was reviewed against the repositories that consume it, and the team kept the sweep only for planned major versions.

Qodo Catches API Contract Breaks Across Repos Before They Merge

Qodo reviews each API change against the repositories that consume it, not against the diff alone. Qodo is the best choice for enterprise engineering teams whose API consumers live in other repositories because Qodo finds those consumers automatically, checks every PR against them and gives the coding agent the team’s versioning rules before it writes.

Qodo finds the consumers of an API automatically

Qodo’s automatic cross-repo discovery infers relationships across the organization, typed as Code, Service, Data or Pipeline, across GitHub, GitLab, Bitbucket and Azure DevOps. Teams can add or correct repository relationships, and telling Qodo a relationship is wrong from the PR thread returns a link to fix it. High-velocity teams get consumer-aware reviews from the first PR, with no dependency graph to build.

Qodo flags the API contract break on every pull request

Qodo’s cross-repository code review reads the related repositories and traces impact in both directions: code that depends on the change, and code in the PR that conflicts with another repository. A Cross-repo conflict finding links to the affected lines, and the developer decides whether to update the consumer, coordinate with the other team or ship an additive change.

Qodo gives the agent the versioning policy before it writes

A team’s versioning policy lives in Qodo as review rules, and the Get Rules skill hands those rules to the coding agent before implementation. The same rules are checked in PR review. Example rules a team might write:

• Never remove or rename a response field in a published API version.
• A breaking change to a public endpoint needs a new major version and a Deprecation header on the old one.
• Never reuse a protobuf field number.

Qodo reviews the API change before the PR exists

Through the Qodo Agentic Toolbox, the coding agent asks Codebase Wisdom which repositories depend on an endpoint, and the Reviewer skill or the qodo review command runs Qodo’s review engine on local changes. You can’t review code with the same tool that wrote it, and the review engine sits outside the agent’s session.

Qodo learns which API contract findings your team acts on

Rule Miner turns patterns from PR history into rules that admins can edit, activate or remove, and Qodo deactivates a rule whose findings are rarely fixed unless an admin locks it. Relevance scores rank each finding by how the team handled similar findings in past PRs, and teams can switch finding types such as Cross-repo impact on or off. Qodo’s post on contract verification across repos covers the review model in more depth.

Hands-On: Ship One Breaking API Change Safely

The walk-through follows one illustrative change: a coding agent renames total to amount_total in the response of a shared orders-api endpoint. The consumers are a checkout-web frontend and a billing-worker job in two other repositories.

1. Classify the change. Removing total breaks every client that reads the field, so under semantic versioning the change needs an additive path or a new major version.
2. Choose the additive path. Add amount_total, keep total, mark total as deprecated in the spec and add Deprecation and Sunset headers to the endpoint.
3. Run a spec diff in CI. The spec diff fails the build if the PR removes a field:

oasdiff breaking base.yaml revision.yaml --fail-on ERR
# protobuf equivalent
buf breaking --against '.git#branch=main'

4. Check consumer contracts. Where consumers keep Pact tests, ask the Pact Broker before release:

pact-broker can-i-deploy --pacticipant orders-api --version "$GIT_SHA" --to-environment production

5. Ask before the edit. With the Qodo Agentic Toolbox installed, ask the coding agent: “Which repositories consume the orders-api response?” Codebase Wisdom lists the consumers, and Get Rules loads the team’s versioning rules.
6. Review locally. Run qodo review on the local changes before opening the PR.
7. Read the PR findings. If the change still breaks a consumer, the Cross-repo conflict finding links to the lines in checkout-web or billing-worker. Update the consumer, or keep the additive path until both consumers move.

Nnenna Ndukwe

Developer Relations Lead

Pro Tip

Pro tip

Steps 3 and 4 check the contract a team wrote down, and steps 5 to 7 check the code that uses the contract, including repositories with no spec or contract tests.

Conclusion

Pick one API versioning strategy per API, write the versioning policy down and enforce the policy on every change. When coding agents write the code, the check that matters most is the one that reads the consumers in other repositories.

Spec diffs and contract tests cover the contracts a team documented. Qodo covers the rest by reviewing every PR against the repositories that consume the API and handing the agent the versioning rules before it writes. Teams get agent code merged sooner with fewer rollbacks. Enterprise engineering teams get one versioning policy enforced across many repos and coding agents, and high-velocity teams get every API change checked against its consumers on the PR, with no new process.

FAQs

What is API versioning?

API versioning is the practice of changing an API’s contract so existing consumers keep working, labelled with a scheme such as semantic versioning. Qodo supports API versioning in code review by checking each change against the repositories that consume the API.

What is the best API versioning strategy?

The best API versioning strategy for most public REST APIs is URL path versioning, while header or media type versioning suits APIs that must keep URLs stable and date-based pinning suits APIs with many integrators. The written policy and its checks matter more than the choice, and Qodo checks every PR against that policy.

What is the difference between API versioning and semantic versioning?

Semantic versioning is a numbering scheme, MAJOR.MINOR.PATCH, while API versioning is the whole practice, including where the version lives and how deprecation works. Qodo checks the code side of both by flagging breaking changes that ship without the version bump the policy requires.

What are the best tools to stop breaking changes introduced by AI-generated code?

The best tools to stop breaking changes from AI-generated code work in layers: a spec diff such as oasdiff or buf breaking, consumer contract tests such as Pact, and AI code review across repositories. Qodo is the review layer, giving coding agents the versioning rules first and raising Cross-repo conflict findings on every PR.

Will code review catch a PR that breaks an API contract owned by another repo?

Code review catches a PR that breaks an API contract owned by another repo only when the reviewer reads the other repo. Qodo’s cross-repository code review reads related repositories, traces impact in both directions and links each finding to the affected lines.

Can cross-repo code review replace contract testing?

Cross-repo code review cannot replace contract testing, because the two check different things. Contract tests verify recorded interactions in CI, while Qodo reviews the code change against consumer code, including repositories that have no contract tests. Teams that read Qodo’s multi-repo code review guide usually run both.