API Versioning Guidelines

Table of Contents

1. Versioning Strategies
2. URI Versioning
3. Header Versioning
4. Media Type Versioning
5. Semantic Versioning
6. Deprecation Policy
7. Versioning Best Practices
8. Migration Strategy
9. Versioning Examples
10. API Evolution

Versioning Strategies

URI Versioning

https://api.dexaminds.com/v1/users
https://api.dexaminds.com/v2/users

Header Versioning

GET /users HTTP/1.1
Host: api.dexaminds.com
Accept: application/json
API-Version: 2023-07-01

Media Type Versioning

GET /users HTTP/1.1
Host: api.dexaminds.com
Accept: application/vnd.dexaminds.v1+json

URI Versioning

Advantages

• Simple to understand and implement
• Easy to debug
• Clear separation between versions

Disadvantages

• Pollutes the URI space
• Breaks URI consistency
• Harder to evolve incrementally

Implementation

# Major version in path
https://api.dexaminds.com/v1/users
https://api.dexaminds.com/v2/users

# With minor version
https://api.dexaminds.com/v1.1/users

Header Versioning

Advantages

• Clean URIs
• More flexible versioning
• Better for caching

Disadvantages

• Harder to test with simple tools
• Less discoverable

Implementation

# Custom header
GET /users HTTP/1.1
Host: api.dexaminds.com
Accept: application/json
X-API-Version: 1.0

# Standard header
GET /users HTTP/1.1
Host: api.dexaminds.com
Accept: application/json;version=1.0

Media Type Versioning

Advantages

• RESTful approach
• Version in content type
• Supports content negotiation

Disadvantages

• More complex to implement
• Less common in the wild

Implementation

# Request with versioned media type
GET /users HTTP/1.1
Host: api.dexaminds.com
Accept: application/vnd.dexaminds.v1+json

# Response
HTTP/1.1 200 OK
Content-Type: application/vnd.dexaminds.v1+json

Semantic Versioning

Version Format: MAJOR.MINOR.PATCH

• MAJOR: Incompatible API changes
• MINOR: Backward-compatible functionality
• PATCH: Backward-compatible bug fixes

Examples

• 1.0.0: First stable release
• 1.0.1: Bug fix release
• 1.1.0: New backward-compatible features
• 2.0.0: Breaking changes

Deprecation Policy

Deprecation Timeline

1. Announcement: Mark API as deprecated in documentation
2. Warning Headers: Include Deprecation and Sunset headers
3. Grace Period: Minimum 6 months before removal
4. Removal: Remove deprecated endpoints in next major version

Deprecation Headers

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: true
Link: <https://api.dexaminds.com/docs/deprecation-policy>; rel="deprecation"; type="text/html"
Sunset: Wed, 30 Jun 2026 12:00:00 GMT

Versioning Best Practices

1. Version Early, Version Often

• Start with version 1.0.0 from day one
• Don’t wait until you have breaking changes

2. Avoid Breaking Changes

• Add new fields instead of changing existing ones
• Make all fields optional when possible
• Use feature flags for experimental features

3. Document Thoroughly

• Document all versions
• Include migration guides
• Provide code samples for each version

4. Use Semantic Versioning

• Follow MAJOR.MINOR.PATCH
• Update versions based on changes
• Document version changes in changelog

5. Plan for Deprecation

• Have a clear deprecation policy
• Give users time to migrate
• Provide migration tools when possible

Migration Strategy

1. Parallel Run

• Run multiple versions in parallel
• Gradually migrate consumers
• Monitor usage statistics

2. Feature Toggles

• Use feature flags for new functionality
• Enable/disable features per request
• Gradually roll out changes

3. API Gateway

• Route requests based on version
• Transform requests/responses
• Handle version-specific endpoints

Versioning Examples

Request Versioning

# URI Versioning
GET /v1/users/123

# Header Versioning
GET /users/123
Accept-Version: 1.0.0

# Media Type Versioning
GET /users/123
Accept: application/vnd.dexaminds.v1+json

Response Versioning

HTTP/1.1 200 OK
Content-Type: application/vnd.dexaminds.v1+json
API-Version: 1.0.0

{
  "id": "123",
  "name": "John Doe",
  "email": "john@example.com"
}

API Evolution

Non-breaking Changes

• Adding new endpoints
• Adding new optional request parameters
• Adding new fields to responses
• Adding new enum values
• Changing the order of fields

Breaking Changes

• Removing or renaming endpoints
• Removing or renaming fields
• Changing field types
• Making required fields optional
• Changing authentication/authorization
• Changing error formats

Versioning in Practice

Current Version (v1)

{
  "id": "123",
  "name": "John Doe",
  "email": "john@example.com"
}

New Version (v2)

{
  "id": "123",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "metadata": {
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-06-30T12:00:00Z"
  }
}

Migration Path

1. Add new fields to v1
2. Update clients to handle both formats
3. Release v2 with new structure
4. Migrate clients to v2
5. Deprecate v1 after migration period

Versioning in OpenAPI/Swagger

Versioned API Definition

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: API for managing users
servers:
  - url: https://api.dexaminds.com/v1
    description: Version 1 API
  - url: https://api.dexaminds.com/v2
    description: Version 2 API (beta)

Versioned Paths

paths:
  /v1/users:
    get:
      summary: Get all users (v1)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserV1'

  /v2/users:
    get:
      summary: Get all users (v2)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserV2'

Monitoring and Analytics

Track Usage by Version

• Monitor API usage per version
• Track adoption rate of new versions
• Identify deprecated endpoints still in use
• Set up alerts for deprecated endpoint usage

Metrics to Monitor

• Request count by version
• Error rate by version
• Response time by version
• Endpoint usage by version
• Client versions in use

Versioning in Practice: Case Study

Initial Release (v1.0.0)

{
  "id": "123",
  "username": "johndoe",
  "email": "john@example.com"
}

New Features (v1.1.0)

• Added createdAt field
• Added status field (ACTIVE, INACTIVE)
• New endpoint: GET /users/{id}/preferences

Breaking Changes (v2.0.0)

• Split username into firstName and lastName
• Removed username field
• New authentication requirements
• Updated error response format

Migration Strategy

1. Release v1.1.0 with new fields
2. Update documentation to show new structure
3. Provide migration guide from v1 to v2
4. Run v1 and v2 in parallel for 12 months
5. Notify users of v1 deprecation
6. Remove v1 endpoints after deprecation period

Versioning in Microservices

API Gateway

Client → API Gateway → v1 Service
                  \-> v2 Service

Service Mesh

Client → Ingress → Service Mesh → v1 Pods
                           \-> v2 Pods

Canary Deployments

• Route small percentage of traffic to new version
• Gradually increase traffic
• Roll back if issues detected

Versioning Checklist

Planning

• Choose versioning strategy
• Document versioning policy
• Plan for backwards compatibility
• Set up monitoring

Implementation

• Add version to API
• Update documentation
• Implement deprecation headers
• Set up analytics

Maintenance

• Monitor version usage
• Plan deprecation timeline
• Communicate changes to users
• Provide migration tools

Final Recommendations

1. Be Consistent: Choose one versioning strategy and stick with it
2. Document Everything: Keep detailed changelogs and migration guides
3. Plan for the Future: Design APIs with evolution in mind
4. Monitor Usage: Track which versions are being used
5. Communicate Changes: Keep users informed about updates and deprecations
6. Be Patient: Give users time to migrate between versions
7. Automate Testing: Test all versions automatically
8. Consider Tooling: Use API gateways and service meshes to manage versions