OpenAPI: API Versioning Strategies

Documenting API Versioning in OpenAPI

API versioning ensures backward compatibility as your API evolves. OpenAPI supports documenting any versioning strategy through its flexible server and path definitions.

URL Path Versioning

The most common approach. Define separate servers or base paths for each version:

servers:
  - url: https://api.example.com/v1
    description: Version 1 (stable)
  - url: https://api.example.com/v2
    description: Version 2 (latest)

Or use path prefixes:

paths:
  /v1/users:
    get:
      summary: List users (v1)
      deprecated: true
  /v2/users:
    get:
      summary: List users (v2)

Header Versioning

parameters:
  - name: API-Version
    in: header
    required: false
    schema:
      type: string
      default: "2024-01-01"
      enum:
        - "2023-06-01"
        - "2024-01-01"
    description: API version date. Defaults to latest stable.

Deprecation Markers

OpenAPI 3.0 supports marking operations as deprecated:

/v1/users:
  get:
    deprecated: true
    summary: List users (use /v2/users instead)
    description: |
      **Deprecated since 2024-06-01.**
      This endpoint will be removed on 2025-01-01.
      Migrate to /v2/users for improved filtering and pagination.

Versioning Strategy Comparison

Strategy	Pros	Cons
URL path (/v1/)	Visible, easy to route	URL changes on version bump
Header (API-Version)	Clean URLs, flexible	Hidden from browser/logs
Query param (?v=1)	Easy to test	Can be lost in caching
Date-based (Stripe style)	Granular, non-breaking	Complex to maintain

Best Practices

1. Document the deprecation timeline (sunset date)
2. Include migration guides in the description
3. Use the deprecated: true flag on old operations
4. Keep both versions documented in the same OpenAPI file during transition
5. Add x-sunset-date custom extension for tooling support