API Versioning Strategies in OpenAPI

API Versioning in OpenAPI

As APIs evolve, versioning prevents breaking changes from affecting existing clients. OpenAPI provides several ways to document versioned APIs, each suited to different versioning strategies.

URL Path Versioning

The most common approach:

openapi: "3.0.3"
info:
  title: My API
  version: "2.0.0"
servers:
  - url: https://api.example.com/v2
    description: Version 2 (current)
  - url: https://api.example.com/v1
    description: Version 1 (deprecated)

Header Versioning

Version in a custom header:

paths:
  /users:
    get:
      parameters:
        - name: API-Version
          in: header
          required: true
          schema:
            type: string
            enum: ["2024-01-01", "2023-06-01"]
            default: "2024-01-01"
          description: API version date

Accept Header Versioning

Using content negotiation:

/users:
  get:
    responses:
      "200":
        content:
          application/vnd.myapi.v2+json:
            schema:
              $ref: "#/components/schemas/UserV2"
          application/vnd.myapi.v1+json:
            schema:
              $ref: "#/components/schemas/UserV1"

Deprecating Endpoints

Mark old operations as deprecated:

paths:
  /users:
    get:
      summary: List users
      deprecated: true
      description: |
        **Deprecated since 2024-01-01.**
        Use GET /v2/users instead.
        This endpoint will be removed on 2025-01-01.

Deprecating Schema Fields

User:
  type: object
  properties:
    id:
      type: string
    username:
      type: string
      deprecated: true
      description: Use 'name' instead
    name:
      type: string

Multiple Versions in One Spec

Use tags and server overrides:

tags:
  - name: Users (v2)
    description: Current user endpoints
  - name: Users (v1)
    description: Legacy user endpoints (deprecated)

paths:
  /v2/users:
    get:
      tags: [Users (v2)]
      summary: List users (current)

  /v1/users:
    get:
      tags: [Users (v1)]
      deprecated: true
      summary: List users (legacy)

Separate Specs per Version

For large APIs, maintain separate spec files:

specs/
  openapi-v1.yaml
  openapi-v2.yaml

Tools like Redocly can merge and diff these specs.

Sunset Header

Document the Sunset header for deprecated APIs:

responses:
  "200":
    headers:
      Sunset:
        schema:
          type: string
          format: date-time
        description: Date after which this endpoint will be removed