What is API versioning? Practical guidance for small teams

API versioning is the practice of exposing and managing incompatible API contracts so existing clients can keep working while the API evolves. A version tells clients which contract they can rely on; it should only change when the external behavior changes in a breaking way, not for internal deployments or refactors (see: https://api7.ai/learning-center/api-101/api-versioning).

Why version an API, and when?

Create a new externally visible version when a change breaks a documented contract and compatibility cannot reasonably be preserved. Typical breaking changes include removing or renaming fields or endpoints, changing field types or required status, or altering authentication in a way existing clients cannot meet. Additive changes, such as new optional fields or new endpoints, often do not require a new version if clients and the contract tolerate unknown fields. Validate assumptions with real consumer tests and telemetry because strict clients can still break on additions (see: https://api7.ai/learning-center/api-101/api-versioning).

For cloud-managed gateways, it is common to run multiple major versions concurrently during migrations so consumers can adopt at their own pace (example procedures: https://docs.cloud.google.com/endpoints/docs/openapi/versioning-an-api).

Common ways to select an API version

Path or URI versioning

Place the version in the URL, for example /v1/orders or /v2/orders. This is highly visible in docs, logs, and routing, and is straightforward for public HTTP APIs. The trade-off is that each major version creates a distinct URI space to operate and maintain (see: https://api7.ai/learning-center/api-101/api-versioning). Many gateways document running v1 and v2 paths in parallel during breaking changes (see: https://docs.cloud.google.com/endpoints/docs/openapi/versioning-an-api).

Header-based versioning

Clients send a dedicated request header, for example API-Version: 2026-09-01. Paths stay stable, but every client, gateway, cache, and observability tool must preserve and account for that header. The version is less visible in the URL and can require extra cache and routing configuration (see: https://api7.ai/learning-center/api-101/api-versioning).

Query parameter versioning

Include a query like ?version=2. This keeps the base path unchanged and is visible, but providers must ensure that caches and routing treat the parameter as part of the contract and do not ignore it (see: https://api7.ai/learning-center/api-101/api-versioning).

Media type (content negotiation)

Use the Accept header to request a representation, for example Accept: application/vnd.example.orders-v2+json. This keeps resource paths stable and distinguishes representations, at the cost of added complexity for clients, docs, and caching (see: https://api7.ai/learning-center/api-101/api-versioning).

How semantic versioning fits

Semantic Versioning (MAJOR.MINOR.PATCH) signals change impact: MAJOR for incompatible changes, MINOR for backward-compatible additions, PATCH for bug fixes that don’t change behavior. It helps classify changes, especially for SDKs and packages. It does not dictate how an HTTP API selects versions at runtime (path, header, etc.), so pair SemVer intent with a concrete selector your stack supports (see: https://blog.axway.com/learning-center/apis/api-management/what-is-semantic-versioning, https://api7.ai/learning-center/api-101/api-versioning).

How to choose a strategy

Consider these questions before you decide: who controls the clients (internal vs. public), how requests will be routed by your gateway, how caches will distinguish versions, how developers will discover the active version, how many concurrent versions your team can safely operate, and what the retirement process will be. No single method is best for all cases; choose one convention and support it consistently across services (see: https://api7.ai/learning-center/api-101/api-versioning).

If you need to run versions in parallel, most managed gateways can serve multiple major versions at once and allow distinct /v1 and /v2 OpenAPI configurations, which is helpful for planned breaking changes and migrations (see: https://docs.cloud.google.com/endpoints/docs/openapi/versioning-an-api).

Lifecycle: deprecate, overlap, retire

Publish a compatibility policy and a migration guide, announce deprecation with timelines, run old and new versions in parallel when necessary, monitor adoption and errors, then retire only when the stated conditions are met (see: https://api7.ai/learning-center/api-101/api-versioning, https://docs.cloud.google.com/endpoints/docs/openapi/versioning-an-api). Some gateways append the version to the public endpoint and, if a client omits it, default to the latest active version; confirm your gateway’s behavior before relying on it (example: https://www.ibm.com/docs/en/wams/wm-api-gateway-saas/11.1.0?topic=apis-versioning).

Related reading on Stack & Method

Understanding push vs pull integration helps plan migrations: What are the differences between REST APIs and webhooks?. For safer upgrades and retries across versions, see Idempotency keys: safe retries without duplicate actions.

FAQs