API Versioning

Controlled evolution: change without surprising consumers

Central principle

Compatibility is perceived by the consumer; versioning is just a coordination mechanism.

In-depth edition - study material and professional reference

radio_button_unchecked Chapter presentation

In the previous chapter, rate limiting, quotas and throttling were presented as part of an API's operational contract. Reducing a limit, changing the consumption unit, or modifying the behavior of a 429 response can break consumers even when no JSON fields have changed. This observation leads to the central theme of this chapter: an API is compliant when it continues to meet legitimate consumer expectations, not just when the OpenAPI file can still be parsed.

API Versioning is often reduced to the choice between putting v1 in the path, in a header or in a parameter. This choice is important, but it only represents the visible part. The real problem is coordinating evolution in a distributed system: contracts have been published, SDKs have been generated, applications have incorporated behaviors and integrations may be outside the direct control of the provider. Changing the API now requires impact analysis, communication, coexistence and evidence of migration.

The life cycle expands this analysis. A version needs to be born with stability criteria, become active, receive corrections, communicate changes, go into depreciation and eventually be withdrawn. Without governance, versions accumulate at the gateway, vulnerabilities remain in old contracts, and consumers only discover retirement when traffic fails.

This chapter presents compatibility models, change taxonomy, version selection strategies, schema evolution, versioning in REST, GraphQL, gRPC and events, versions and revisions in Azure API Management, depreciation with Deprecation and Sunset headers, telemetry, contract testing and the expand-migrate-contract pattern.

How to study this chapter

For each change, answer: who produces the data, who interprets it, what past behavior was promised, which consumers still depend on it, and what evidence demonstrates the change is safe. Avoid classifying changes just by the appearance of the diff.

Learning Objectives

• Explain why API evolution is a distributed contract problem and not just a code problem.
• Distinguish syntactic, structural, semantic, behavioral and operational compatibility.
• Classify changes in requests, responses, schemas, errors, security and limits.
• Critically apply semantic versioning to remote APIs.
• Compare versioning by path, query string, header, media type and data.
• Plan coexistence, migration and retirement of versions in API Gateways.
• Differentiate public version, revision , implementation release and specification version.
• Use Deprecation , Sunset , changelogs and migration guides.
• Apply semantic diff , contract tests, telemetry and quality gates.
• Diagnose incorrect routing, contract drift and consumers stuck on old versions.

Chapter structure

• 28.1 Why APIs need to evolve; 28.2 Public contract; 28.3 Compatibility dimensions; 28.4 Data direction; 28.5 Taxonomy of changes; 28.6 SemVer ; 28.7 Version dimensions; 28.8Path; 28.9 Query, header and media type; 28.10 Versions by date; 28.11 Choice criteria; 28.12 Schemas and enums; 28.13 Operations, errors, security and limits; 28.14 REST, GraphQL, gRPC and events; 28.15 Persistent data; 28.16 Coexistence; 28.17 Azure APIM; 28.18 Life cycle; 28.19 Depreciation and Sunset ; 28.20 Communication; 28.21 Telemetry; 28.22 Diff and tests; 28.23 Expand-migrate-contract ; 28.24 Gateway and troubleshooting; 28.25 Case studies and laboratories.

radio_button_unchecked 28.1 Why APIs need to evolve

APIs evolve because the domain changes. New regulatory rules, products, channels, partners, and security requirements require additional information or different behaviors. There are also technical reasons: correcting modeling, improving performance, replacing dependencies, adopting new formats and eliminating vulnerabilities. Freezing an interface forever transfers costs to the backend, which starts maintaining adaptations and exceptions indefinitely.

At the same time, a published API creates dependency. The consumer can compile an SDK, persist responses, validate enums as closed sets, use an HTTP status for flow control, or assume certain ordering. These assumptions do not always appear in the formal contract. A small change to the provider can be disruptive for applications that have incorporated the previous behavior.

Safe evolution separates internal change from observable change. Refactoring classes, changing databases or moving the service between clusters does not require a new version when the contract and promised features remain. Changing a mandatory field, removing an accepted value or changing operation semantics affects the public interface, even if the URL remains the same.

Architecture principle

New deployment does not automatically imply new public version. A new public version is required when the observable contract changes in an incompatible way or when the organization needs to explicitly offer different behaviors.

radio_button_unchecked 28.2 The public contract of an API

The public contract includes everything that the consumer can observe and is authorized to trust. Paths, methods, parameters, schemas, status, headers, media types and security requirements form the explicit part. Agreed latency, limits, ordering, consistency, idempotence, retry policy and availability window can form an equally relevant operational part.

The agreement is not limited to the OpenAPI document. It also exists in the gateway, deployment, portal, SDKs, and actual production behavior. When these representations diverge, contract drift arises. Comparing the new proposal only with an outdated file produces false security; the baseline must match the actually published and supported version.

The consumer does not need to know internal details, but they do need predictability. The provider can change the implementation freely while preserving semantics and guarantees. The boundary between internal freedom and external commitment is the essence of a mature versioning strategy.

radio_button_unchecked 28.3 Compatibility dimensions

Syntactic compatibility means that the message can still be parsed. Structural compatibility indicates that types, properties, and constraints remain accepted. Semantic compatibility requires that the meaning remains. Behavioral compatibility looks at effects, transitions, and errors. Operational compatibility includes performance, availability, limits, and features necessary for the consumer to meet their own objectives.

An API can remain structurally compatible and break semantically: the field remains a string, but the same value starts to mean another state. It can also maintain semantics and fail operationally when pagination decreases, the rate limit is reduced or the timeout grows beyond the consumer's journey. Contract diff is necessary but not sufficient.

radio_button_unchecked 28.4 Data direction and consumer perspective

The same change can have the opposite impact depending on the direction of the data. In a request, the consumer produces and the provider interprets. Making provider validation more permissive generally preserves old requests; making it more restrictive may reject them. In a response, the provider produces and the consumer interprets; adding possibilities may require tolerance that the client does not have.

Adding enum value to request is often supported for existing consumers because they can continue to send known values. Adding value to response may break clients that mapped the set as closed. Diff tools need to know this direction; Generic rules like “addition is compatible” produce false negatives.

Callbacks, webhooks and events reverse traditional roles. The organization that normally acts as a server starts producing messages consumed by third parties. The review needs to clearly record who produces and who interprets each element.

radio_button_unchecked 28.5 Taxonomy of changes

Additive changes add elements without removing existing ones: new operation, optional field or additional media type. They are usually compatible, but they are not automatically safe. Additional field in response may break strict deserializers; new enum value can reach a switch without default case; new route may collide with generic route on the gateway.

Restrictive changes reduce the set of accepted messages. Making a field mandatory, decreasing maxLength, eliminating enum or accepting fewer formats tends to break previously valid requests. Substitutive changes swap one element for another, such as renaming a property, path, or OAuth scope. Behavioral changes preserve structure, but alter rules, side effects, consistency, ordering or error policy.

The classification must record direction, range and mitigation. A change can be compatible for requests and incompatible for responses; safe for tolerant clients and risky for generated SDKs; acceptable in preview and inadequate in production.

radio_button_unchecked 28.6 Semantic versioning and its limits

Semantic Versioning uses MAJOR.MINOR.PATCH. The major increases when there is an incompatible change in the public API; minor when there is compatible functionality; patch when there is a compatible patch. The model is valuable because it forces you to declare a public interface and assigns meaning to the number change.

In remote APIs, SemVer needs critical thinking. The consumer does not necessarily choose an exact version of the server as they choose a library. The provider can continuously deploy under the same endpoint, and operational characteristics are also part of the experience. Publishing 1.4.3 to info.version does not determine how the gateway will select the version.

Many organizations expose only the major, as v1, and treat minor and patch as compatible releases under the same interface. This approach reduces endpoint proliferation, but requires strict discipline in compatibility classification. SemVer does not replace deprecation , support or migration policy.

radio_button_unchecked 28.7 Public version, contract, implementation and specification

A mature architecture distinguishes different numbers. The public version identifies a consumer-selectable interface. The contract version identifies a revision of the OpenAPI document or schema. The implementation version identifies the build or release of the backend. The version of the specification, such as OpenAPI 3.1, tells you which dialect describes the document.

These numbers change for different reasons. The backend can receive multiple deployments without changing the public version. The contract can correct a description without changing the runtime. Migrating the description from OpenAPI 3.0 to 3.1 does not require creating v2. Confusing dimensions produces unstable URLs and makes auditing difficult.

Logs and metrics must record requested public version, gateway revision , backend build and contract checksum. This correlation allows you to investigate when responses seemingly from the same API came from different implementations.

radio_button_unchecked 28.8 Versioning in the URI path

Path versioning places the identifier in a visible part of the URI, such as /v1/clientes. It is simple to understand, appears in logs without header inspection, and is usually easily routed through gateways. It also allows documentation and policies separated by base path.

The main disadvantage is making the version part of the resource identity. /v1/clientes/10 and /v2/clientes/10 are different URIs, even though they represent the same entity. Links, caches and integrations need to be updated. The pattern works best when only incompatible major changes generate new path.

The gateway must prevent ambiguities, such as /v1beta colliding with /v1, and must define the behavior of unversioned paths. Silently redirecting to the newer version can be dangerous; explicit rejection or documented default version are more predictable choices.

Example version on path

GET /v2/clientes/123 HTTP/1.1
Host: api.empresa.example
Accept: application/json

radio_button_unchecked 28.9 Query string, header and media type

The query string expresses the version as a parameter, for example ?api-version=2026-07-01. Preserves the path and is common in services that version by date. Gateways and caches need to include the parameter in the key and prevent unknown values from being silently ignored.

A dedicated header, like Api-Version: 2, keeps the URI stable and makes the negotiation explicit. The disadvantage is less visibility in simple tools and logs that do not record headers. WAF, CORS, proxies and observability need to preserve the field correctly.

Versioning by media type uses Accept, such as application/vnd.empresa.cliente-v2+json. It combines representation format and version and aligns with content negotiation. However, it increases tooling complexity and requires Vary: Accept when the response changes depending on the header.

Versions by date, such as 2026-07-01, communicate a temporal baseline rather than a major sequence. They are useful on platforms with many coordinated changes or when the consumer needs to fix known behavior on a certain date. The date does not necessarily mean deployment date; it represents a published contract and must be immutable once made available.

Another approach combines major release with stability levels: alpha, beta and stable. Alpha supports frequent changes and limited support; beta signals greater maturity, but can still evolve; stable offers compatibility and support commitments. These labels only have value when there are clear promotion and withdrawal criteria.

Releases by date and stability labels do not eliminate the need for compatibility. They simply better express the lifecycle model chosen by the organization.

radio_button_unchecked 28.11 Criteria for choosing a strategy

There is no universally better mechanism. The decision needs to consider consumers, caching, observability, portals, SDKs, infrastructure, corporate policies and operation capacity. Path tends to favor simplicity; header and media type favor stable URI; query works well for date baselines. Organizational consistency is more important than individual preference.

The strategy also needs to define missing, unknown, and retired versions. The gateway must respond in a predictable way, with a standardized error message and link to documentation. Silent fallback to the closest version can mask failures and produce incorrect behavior.

When different teams adopt incompatible mechanisms, the cost appears in the portal, customers, and observability. An enterprise standard must allow for justified exceptions, but must maintain common compatibility, lifecycle, and depreciation criteria.

radio_button_unchecked 28.12 Evolution of schemas, fields, enums and nullability

Adding an optional field to a request is usually supported because old clients simply don't send it. Making it mandatory breaks existing messages. In response, adding field may break strict clients. Removing a field, changing type, decreasing limits or changing nullability tends to be incompatible.

Enums require special attention. In request, adding value accepted by the server does not force old clients to use it. In response, the new value may break SDKs that generated closed enum. An evolution policy must define whether consumers need to ignore unknown values or map an UNKNOWN state.

JSON Schema, OpenAPI, and SDK generators can interpret missing, null, and empty values differently. Changing a field from nullable to non-nullable, changing default or omitting properties can affect logic even when the nominal type remains the same.

Add operation is generally supported, but may collide with generic routes. Removing or renaming path or method is breaking. Making a parameter mandatory, changing query location to header, changing encoding or eliminating media type requires coordinated migration.

HTTP status and error templates are part of the contract. Changing 404 to 200 with empty body, changing 409 to 422, or replacing error structure can break retry, observability, and flow control. The provider must maintain stable codes or provide a new version with clear migration guidance.

Security changes are often incompatible: require new OAuth scope, change audience, remove API key, require mTLS or change request signature. The same goes for rate limits, quotas, timeouts and paging. The public version must reflect changes that make existing consumers unviable, even if the payload remains identical.

radio_button_unchecked 28.14 Versioning in REST, GraphQL, gRPC and events

In REST, versions often appear in the path, query, header or media type. In GraphQL, evolution usually occurs in the schema itself by adding and deprecating fields; creating /v2 for any changes eliminates some of the flexibility of the model. Incompatible fields can coexist temporarily, with @deprecated and per-operation telemetry.

In gRPC and Protocol Buffers, compatibility depends on field numbers. Removed fields must be marked as reserved and old numbers cannot be reused. Packages and services may include major in the nomenclature when there is a breakdown. Binary compatibility needs to be tested against clients generated in previous versions.

Events and messaging require special attention because messages may remain stored. The consumer can process old events after a new version is published. Strategies include schema registry, backward/forward compatibility, envelope versioning and tolerant consumers. Updating producer and consumer simultaneously is rarely secure in distributed environments.

radio_button_unchecked 28.15 Persistent data and migrations

API changes often depend on changes in the database. Adding mandatory field in v2 may require backfilling of historical records. Changing an identifier or normalizing an entity can affect links, events, and caches. Migration needs to consider old data, rollback and coexistence between application versions.

The expand-and-contract pattern also applies to the bank: first add new column or structure without removing the old one; then write in both formats or backfill; then migrate readers; finally remove the old structure when there are no dependents. Instant exchanges increase risk because code and data rarely change atomically across the entire platform.

When v1 and v2 need to read and write the same domain, the organization must define source of truth, transformation, and consistency. Adapters in the gateway resolve superficial differences; Deep semantic changes belong to the domain or dedicated compatibility services.

radio_button_unchecked 28.16 Coexistence of versions and adapters

Coexistence allows consumers to migrate at different paces. The gateway can route v1 and v2 to separate backends, to the same implementation with internal branches, or to a facade that adapts contracts. Each option has a cost. Separate backends increase isolation but duplicate operations; shared implementation reduces infrastructure but accumulates conditionals; adapters work well for representation differences, but not for incompatible business rules.

An old version shouldn't stay around indefinitely just because it still gets traffic. The provider needs to measure consumers, classify criticality, define deadline and offer migration support. Without sunset , versions become permanent products and expand the attack surface.

Policies, caching, authentication, observability, and SLAs may differ by version. The version set needs to record recommended version, state, owner, documentation and replacement relationship.

radio_button_unchecked 28.17 Versions and revisions in Azure API Management

In Azure API Management, versions group related APIs and allow you to expose incompatible interfaces by path, query, or header. They are appropriate when consumers need to explicitly select different contracts. Each version can have its own operations, policies, products and documentation.

Revisions solve another problem: changing and testing an API without creating a new public version. A revision can receive non- breaking changes , be tested separately, and then become current. The changelog can be published to consumers. Revision is not a substitute for versioning when the contract is incompatible.

The rule of thumb is simple: non-breaking change can be prepared as a revision and promoted to the current version; Breaking change requires new version and migration plan. The pipeline needs to prevent an experimental review from becoming current without testing and approval.

radio_button_unchecked 28.18 Lifecycle states and governance

A version needs clear states. Design indicates contract under review; preview allows pilots and admits changes; active offers support and SLA; deprecated informs that the version is no longer recommended; sunset sets withdrawal date; retired indicates that the traffic is no longer served.

Every transition needs entry and exit criteria. To become active, for example, the contract must be published, policies tested, capacity validated and owner defined. To be deprecated, there must be a functional replacement, migration guide and deadline. To withdraw, telemetry needs to demonstrate absence or formal acceptance from remaining consumers.

Governance must prevent orphaned versions: without owner, without documentation, without observability or with certificate and unmaintained dependencies.

Depreciation does not mean immediate termination. It communicates that the feature or version is no longer recommended and may be removed in the future. The consumer needs a replacement, deadline, justification and migration documentation. The sunset date represents the moment after which the resource tends to stop responding.

The Deprecation header allows you to signal that the resource will be or has already been deprecated. The relation deprecation link may point to additional documentation. The Sunset header tells you when the URI is likely to become unavailable. These signals complement portal, email and changelog ; They do not replace active consumer management.

The Sunset date must not be earlier than the depreciation date. The gateway can insert these headers per version, but the configuration needs to be consistent with the actual catalog and retirement plan.

Example of Depreciation Signaling

HTTP/1.1 200 OK
Deprecation: @1782863999
Sunset: Wed, 30 Jun 2027 23:59:59 GMT
Link: <https://developer.example/migrations/v2>; rel="deprecation"

radio_button_unchecked 28.20 Communication, changelog and migration guide

Effective communication answers what changed, why it changed, who is affected, when the version will be retired and how to migrate. The changelog should be consumer-oriented, not a list of commits. The guide needs to show field mapping, status differences, new security requirements, and before/after examples.

Critical consumers may require direct contact, approval window and follow-up. Generic notifications on the portal are insufficient when the version participates in payments, Open Finance or regulated journeys. The organization must record confirmation, risks and exceptions.

The portal must indicate recommended version, status of others, documentation, SDKs, changelog and dates. Broken links or conflicting documentation reduce confidence and prolong migrations.

radio_button_unchecked 28.21 Consumer inventory and telemetry

It is not possible to safely remove what is not measured. The inventory must identify application, owner, tenant, environment, version used, criticality and volume. Isolated IP is insufficient in environments with NAT, proxies and shared pools. client_id, subscription key, certificate, or workload identity are better keys.

Telemetry needs to cover periodic traffic and seasonal journeys. One version may appear inactive for days and only be used at the monthly close. Useful metrics include calls by version, unique consumers, errors, operations used, last activity, and migration percentage.

Logs must preserve the requested version and the effectively routed version. When the gateway applies default or rewrite, the difference needs to be visible to avoid misdiagnosis.

radio_button_unchecked 28.22 Semantic diff , contract tests and quality gates

Textual diff identifies changed lines, but does not understand impact. Semantic diff interprets operations, schemas, data direction, required, enums and restrictions. Still, tools don't capture every behavioral change. Human review needs to analyze semantics, security, and operation.

The pipeline must validate syntax, linting, corporate rules, diff against the published baseline , contract testing, consumer testing, and exception approval. The baseline cannot just be the main branch; it must represent the artifact actually in production.

Consumer-driven contract testing helps reveal concrete dependencies, but does not replace the provider's contract. A good strategy combines OpenAPI or official schema, compatibility testing and real telemetry.

The expand-migrate-contract pattern prevents instant switching. In the expansion phase, the provider accepts old and new: it adds a field, endpoint or format without removing the existing one. In migration, consumers are moved gradually, with telemetry and support. In contraction, the old element is removed only when there are no relevant dependents.

To rename a mandatory field, for example, the server can accept both names, temporarily respond with both and record which form each consumer uses. After everyone migrates, the old name is deprecated and removed in the new major or defined compatibility window .

The pattern temporarily increases complexity, but reduces risk, facilitates rollback and eliminates the need to synchronize deployments of all consumers.

Expand, migrate and contract

radio_button_unchecked 28.24 API Gateways, routing and troubleshooting

The gateway is a natural version selection point, but it should not hide incompatible semantics. Policies can extract path, query or header version, validate values, route to backend, insert deprecation headers and record telemetry. The order of policies needs to be predictable: identify version before caching, specific authentication and routing.

Common failures include unexpected default version, incorrect rewrite, cache shared between versions, policy inherited only in part, backend v2 receiving v1 traffic and documentation pointing to another base URL. Logs must record the received version, resolved version, chosen backend, revision and contract checksum.

When troubleshooting, reproduce the request with all selection elements and compare gateway, portal, OpenAPI and backend. A 404 could mean a non-existent operation in the version, an unpublished route or a misconfigured version set . A 200 with an old payload may indicate incorrect caching or routing.

radio_button_unchecked 28.25 Case studies and labs

Case Study 1: A customer API needs to replace idCliente with customerId. The team uses temporary expansion, accepts both in requests, responds with both during migration, measures usage and publishes v2 only when other incompatible changes justify a new major.

Case study 2: a payments API now requires mTLS and a new audience. As the change affects consumer credentials and infrastructure, the team creates v2, maintains v1 for a defined period, distributes certificates in approval and uses Deprecation and Sunset in production.

Case study 3: In Azure APIM, a description fix and new optional field are prepared as v2 revision . After testing, the revision becomes current without creating v3. Months later, an incompatible contract change generates v3 in the same version set .

Suggested labs

1) Compare two OpenAPI documents and classify the changes. 2) Configure versioning by path and header on a laboratory gateway. 3) Simulate Deprecation and Sunset . 4) Create telemetry by version and consumer. 5) Run an expand-migrate-contract migration with renamed field.

radio_button_unchecked Chapter summary

API Versioning is a coordination mechanism for observable changes. The objective is not to generate numbers, but to allow evolution with controlled risk. Compatibility needs to be analyzed in the syntactic, structural, semantic, behavioral and operational dimensions.

The direction of the data changes the classification of changes. Strategies based on path, query, header, media type or data have trade-offs and need to work across the entire chain. Public version, revision , release and specification version are different dimensions.

The lifecycle turns depreciation and retirement into auditable processes. Deprecation and Sunset improve communication at runtime, but inventory, telemetry, migration guides and adoption confirmation determine security. Semantic diff , tests and expand-migrate-contract reduce risk without preventing evolution.

Next step of the course

With versions and lifecycle governed, the next chapter delves into Service Mesh, including Istio, Linkerd, and Envoy, and shows how policies, identity, and observability are applied to inter-service communication.

radio_button_unchecked API Versioning Checklist

• The baseline corresponds to the contract actually published and supported.
• The change was analyzed in syntactic, structural, semantic, behavioral and operational dimensions.
• Data direction and behavior of SDKs were considered.
• New version is created only when there is incompatibility or explicit need for coexistence.
• The selection mechanism works across client, cache, WAF, gateway, portal, and observability.
• Public version, revision , build and specification version are separated.
• Depreciation offers a substitute, guide, deadline, owner and support channel.
• Deprecation , Sunset , portal and catalog are consistent.
• The inventory identifies consumers by application or identity, not just by IP.
• The pipeline runs parser, linter, diff, testing and passing exceptions.
• Withdrawal has evidence, communication and recovery plan.

radio_button_unchecked Exercises

• Explain why adding a field to response can be breaking.
• Differentiate between structural, semantic and operational compatibility.
• Classify enum addition into request and response.
• Differentiate public version, contract, revision , build and version of the OpenAPI Specification.
• Compare path, query, header, media type and version by date.
• Explain when a revision is preferable to a new version in Azure APIM.
• Write HTTP response with Deprecation , Sunset and Link to migration guide.
• Describe an expand-migrate-contract plan to rename required field.
• Propose metrics to decide whether v1 can be removed.
• Describe how to investigate when v2 returns behavior from v1.

radio_button_unchecked Glossary

radio_button_unchecked Technical references

• IETF. RFC 9110 - HTTP Semantics.
• IETF. RFC 8594 - The Sunset HTTP Header Field.
• IETF. RFC 9745 - The Deprecation HTTP Response Header Field.
• Microsoft Learn. Versions in Azure API Management.
• Microsoft Learn. Revisions in Azure API Management.
• Google Cloud API Design Guide. AIP-185: API Versioning.
• Semantic Versioning Specification 2.0.0.
• OpenAPI Initiative. OpenAPI Specification 3.1.
• Protocol Buffers Documentation. Updating a Message Type.
• GraphQL Specification and schema deprecation practices.

Update note

Standards, managed services, and tools evolve. Before automating version sets, revisions, depreciation or semantic diff , validate the official documentation of the deployed version and test the behavior in an authorized environment.