API Versioning Strategies for Long-Term Projects

API versioning is essential for any public or internal API that evolves over time. Without a versioning strategy, changing an endpoint’s behavior will break existing clients. A well-designed versioning approach lets you add features, fix bugs, and improve performance without disrupting users who depend on the current contract. This article covers the main versioning strategies — URL, header, and query parameter — along with deprecation practices and migration patterns.

URL Path Versioning

The most common and simplest approach is to include the version number in the URL path, such as /api/v1/users and /api/v2/users. This makes the version explicit, easy to route at the web server level (Nginx, API gateway), and straightforward for clients to understand and configure. The main downside is URL bloat — every endpoint URL changes when you bump the version, which can be annoying for clients that hardcode URLs. URL versioning also makes it tempting to create a new version for every small change, which leads to many underused API versions that must all be maintained.

# URL versioning — best for public APIs with many consumers
GET /api/v1/users
POST /api/v1/users
GET /api/v2/users  # new version with breaking changes

Header Versioning

Header versioning keeps the URL clean by specifying the version in a custom HTTP header or the Accept header using a media type parameter. This approach keeps URLs stable — /api/users always works — but makes version discovery harder for developers because the version is not visible in the URL or in documentation examples. It also adds complexity to client setup since custom headers must be configured. API gateways and proxies may also strip or modify custom headers, which can cause unexpected routing.

# Accept header versioning (media type)
GET /api/users
Accept: application/vnd.myapp.v1+json

# Custom header versioning
GET /api/users
X-API-Version: 1

# Response with deprecation headers
HTTP/1.1 200 OK
Sunset: Sat, 01 Nov 2027 00:00:00 GMT
Deprecation: true
Link: ; rel="successor-version"

The Sunset header tells clients when the old version will be removed, the Deprecation header signals that this version is deprecated, and the Link header with rel="successor-version" points to the replacement. These headers give clients a clear migration timeline without requiring them to check external documentation or changelogs.

Query Parameter Versioning

Query parameter versioning appends the version as a query string: /api/users?version=1. This is the easiest to implement on the server side (just read a query parameter) but has significant drawbacks. Query parameters are often ignored by caching layers, so different versions of the same resource are not cached separately. They also clutter API logs and URLs, and clients can accidentally omit the parameter entirely, causing unexpected behavior from the default version.

Backward-Compatible Changes

Before creating a new API version, consider whether the change can be made backward-compatible. Adding new optional fields to a response, adding new endpoints, or making previously required fields optional are all safe changes that do not require a version bump. The guideline is: be liberal in what you accept and conservative in what you send. Always include fields that clients might depend on rather than removing them, and use null or sensible defaults for new optional fields so existing parsers do not break.

# Backward-compatible: add new fields to response
{
  "id": 42,
  "name": "Alice",
  "email": "alice@example.com",
  "created_at": "2026-01-15T10:00:00Z",
  "profile_url": null        # new field, null by default
}

# Backward-compatible: make previously required field optional
# Old: {"username": "alice"} — username is required
# New: {"username": "alice", "email": "alice@example.com"} — username still works

Deprecation and Migration

When a breaking change is unavoidable, deprecate the old version with a clear timeline. Support each version for 6-12 months after announcing deprecation. Communicate the deprecation through multiple channels: deprecation headers in API responses, email notifications to registered developers, changelog entries, and documentation banners. Provide a migration guide that explains what changed and how to update client code. After the sunset date, return HTTP 410 Gone for deprecated endpoints rather than silently failing — this gives a clear signal to clients that the endpoint is no longer available.

# OpenAPI deprecation marker
paths:
  /api/v1/users:
    get:
      deprecated: true
      summary: "List users (deprecated — use /api/v2/users)"
      responses:
        '200':
          description: "User list"

# Server-side version router (Python example)
from fastapi import APIRouter

v1_router = APIRouter(prefix="/api/v1")
v2_router = APIRouter(prefix="/api/v2")

@v1_router.get("/users")
def list_users_v1():
    return [{"id": 1, "name": "Alice"}]  # old schema

@v2_router.get("/users")
def list_users_v2():
    return [{"id": 1, "name": "Alice", "email": "alice@example.com"}]

The best versioning strategy depends on your audience. Public APIs with many external consumers benefit from URL versioning’s explicitness. Internal APIs within a single organization can use header versioning for cleaner URLs. Whichever strategy you choose, minimize the number of versions you maintain — ideally no more than two at a time — and automate the deprecation process so that sunset dates are enforced consistently.