veza/docs/archive/root-md/API_VERSIONING_STRATEGY.md

API Versioning Strategy

INT-011: Add API versioning strategy

Date: 2025-12-25
Status: Completed

Overview

This document defines the comprehensive API versioning strategy for Veza Backend API. It provides guidelines for both API developers and consumers on how to handle API versions, breaking changes, and migrations.

Current Version: v1
Status: Active
Implementation: URL Path Versioning (primary), Header-based (supported)

Versioning Methods

The Veza API supports multiple methods for specifying the API version, in order of precedence:

1. URL Path Versioning (Primary)

The version is included in the URL path:

GET /api/v1/tracks
POST /api/v1/playlists
GET /api/v2/users/me

Advantages:

• Clear and explicit
• Easy to understand
• RESTful
• Cache-friendly

Format: /api/v{major}/...

2. Header-Based Versioning (Supported)

Clients can specify the version using HTTP headers:

X-API-Version Header

X-API-Version: v1

Accept Header (Content Negotiation)

Accept: application/vnd.veza.v1+json

Advantages:

• Clean URLs
• Flexible for clients
• Supports content negotiation

Note: When using header-based versioning, the URL path should still include /api/ but the version can be omitted or different.

Version Format

• Format: v{major}
• Examples: v1, v2, v3
• Major versions indicate breaking changes
• No minor/patch versions in the API path (semantic versioning is used for the application itself)

Version Lifecycle

Current Version: v1

• Status: Active
• Released: 2025-01-01
• Deprecation Date: TBD
• End of Life: TBD
• Breaking Changes: None planned
• Description: Current stable API version

Version States

1. Active: Current recommended version, fully supported
2. Deprecated: Still functional but will be removed in the future
3. End of Life: No longer supported, requests will fail

Version Lifecycle Timeline

┌─────────────┐
│   Active    │ ← Current version, fully supported
└──────┬──────┘
       │
       │ (6+ months notice)
       ▼
┌─────────────┐
│ Deprecated  │ ← Still works, but marked for removal
└──────┬──────┘
       │
       │ (12+ months support)
       ▼
┌─────────────┐
│ End of Life │ ← Removed, requests fail
└─────────────┘

Breaking vs Non-Breaking Changes

Breaking Changes (Require New Major Version)

Breaking changes require a new major version (e.g., v1 → v2):

Request Changes

• ✅ Removed endpoints
• ✅ Changed HTTP methods (GET → POST)
• ✅ Removed required fields in request body
• ✅ Changed field types (string → integer)
• ✅ Changed field names (camelCase → snake_case)
• ✅ Changed validation rules (making optional fields required)
• ✅ Changed authentication mechanisms

Response Changes

• ✅ Changed response structure (removing fields)
• ✅ Changed field types in responses
• ✅ Changed error response format
• ✅ Removed response fields
• ✅ Changed HTTP status codes for same endpoint

Examples of Breaking Changes

// v1 Response
{
  "id": "123",
  "name": "Track Name"
}

// v2 Response (BREAKING - removed 'name', added 'title')
{
  "id": "123",
  "title": "Track Name"
}

Non-Breaking Changes (Same Version)

These changes can be made within the same version:

Request Changes

• ✅ New optional fields in request body
• ✅ New query parameters
• ✅ New endpoints
• ✅ Relaxed validation (making required fields optional)

Response Changes

• ✅ New optional fields in responses
• ✅ New endpoints
• ✅ New error codes (additional error types)
• ✅ Performance improvements
• ✅ Bug fixes (fixing incorrect behavior)

Examples of Non-Breaking Changes

// v1 Response
{
  "id": "123",
  "name": "Track Name"
}

// v1 Response (NON-BREAKING - added optional field)
{
  "id": "123",
  "name": "Track Name",
  "description": "Optional description"  // New field
}

Creating a New API Version

When to Create a New Version

Create a new major version when:

1. You need to make breaking changes
2. You want to introduce significant architectural changes
3. You need to deprecate old patterns
4. You want to clean up technical debt

Process for Creating v2 (Example)

Step 1: Planning (3-6 months before release)

1. Identify breaking changes

   • List all breaking changes
   • Document impact on consumers
   • Create migration guide

2. Design new version

   • Design new endpoints
   • Design new request/response formats
   • Plan backward compatibility strategy

3. Announce to consumers

   • Send deprecation notice for v1
   • Announce v2 release date
   • Provide migration timeline

Step 2: Implementation

1. Create v2 handlers

   // New v2 handler
   func (h *TrackHandler) GetTrackV2(c *gin.Context) {
       // v2 implementation
   }
   

2. Register v2 version

   vm.RegisterVersion(&APIVersion{
       Version:     "v2",
       Deprecated:  false,
       Description: "New API version with improved endpoints",
   })
   

3. Add v2 routes

   v2 := router.Group("/api/v2")
   v2.GET("/tracks/:id", trackHandler.GetTrackV2)
   

4. Update tests

   • Add tests for v2 endpoints
   • Test backward compatibility
   • Test migration scenarios

Step 3: Release

1. Deploy v2

   • Deploy to staging
   • Test thoroughly
   • Deploy to production

2. Monitor usage

   • Track v1 vs v2 usage
   • Monitor errors
   • Collect feedback

3. Update documentation

   • Update Swagger/OpenAPI docs
   • Update migration guides
   • Update examples

Step 4: Deprecation (6-12 months after v2 release)

1. Mark v1 as deprecated

   vm.RegisterVersion(&APIVersion{
       Version:     "v1",
       Deprecated:  true,
       SunsetDate:  "2026-12-31T00:00:00Z",
       Description: "Deprecated - migrate to v2",
   })
   

2. Add deprecation headers

   • X-API-Version-Deprecated: true
   • Sunset: 2026-12-31T00:00:00Z

3. Notify consumers

   • Send deprecation notices
   • Provide migration timeline
   • Offer support for migration

Step 5: End of Life (12+ months after deprecation)

1. Remove v1 support

   • Remove v1 routes
   • Remove v1 handlers
   • Update documentation

2. Final notification

   • Send final notice
   • Provide last migration window
   • Close v1 support tickets

Guidelines for API Developers

When Adding New Features

1. Check if it's breaking

   • If breaking → new major version
   • If non-breaking → same version

2. Document changes

   • Update Swagger annotations
   • Update API documentation
   • Add migration notes if needed

3. Maintain backward compatibility

   • During deprecation period
   • Test both versions
   • Don't break existing consumers

Code Organization

internal/
├── handlers/
│   ├── track_handler.go      # v1 handlers
│   └── track_handler_v2.go   # v2 handlers (when needed)
├── api/
│   ├── router.go             # Route setup
│   └── versioning.go         # Version management

Testing Strategy

1. Test both versions

   func TestTrackEndpoint_V1(t *testing.T) {
       // Test v1 endpoint
   }
   
   func TestTrackEndpoint_V2(t *testing.T) {
       // Test v2 endpoint
   }
   

2. Test backward compatibility

   • Ensure v1 still works
   • Test migration scenarios
   • Test deprecation warnings

Guidelines for API Consumers

Best Practices

1. Always specify version explicitly

   # Good
   GET /api/v1/tracks
   
   # Also good
   GET /api/tracks
   X-API-Version: v1
   

2. Monitor deprecation notices

   • Check /api/versions endpoint
   • Monitor response headers
   • Subscribe to API updates

3. Test new versions early

   • Test in staging
   • Migrate gradually
   • Don't wait until EOL

4. Handle version errors gracefully

   if (response.status === 400 && response.body.error === "Unsupported API version") {
       // Handle version error
       console.log("Available versions:", response.body.available_versions);
   }
   

Migration Checklist

When migrating from v1 to v2:

• Review breaking changes documentation
• Test v2 endpoints in staging
• Update API client code
• Update request/response handling
• Test all affected features
• Update error handling
• Deploy to production
• Monitor for issues
• Remove v1 code after successful migration

Version Information Endpoint

GET /api/versions

Returns information about all available API versions:

{
  "current_version": "v1",
  "versions": {
    "v1": {
      "version": "v1",
      "deprecated": false,
      "description": "Current stable API version"
    },
    "v2": {
      "version": "v2",
      "deprecated": false,
      "description": "New API version",
      "sunset_date": null
    }
  }
}

Response Headers

The API includes version information in response headers:

• X-API-Version: Current version being used
• X-API-Version-Deprecated: true if version is deprecated
• Sunset: RFC3339 date when version will be removed (if deprecated)

Examples

Using URL Path Versioning

# v1 endpoint
curl https://api.veza.app/api/v1/tracks

# v2 endpoint
curl https://api.veza.app/api/v2/tracks

Using Header Versioning

# Using X-API-Version header
curl -H "X-API-Version: v1" https://api.veza.app/api/tracks

# Using Accept header
curl -H "Accept: application/vnd.veza.v1+json" https://api.veza.app/api/tracks

Handling Deprecated Versions

# Response includes deprecation headers
curl -H "X-API-Version: v1" https://api.veza.app/api/tracks

# Response headers:
# X-API-Version: v1
# X-API-Version-Deprecated: true
# Sunset: 2026-12-31T00:00:00Z

Decision Matrix

Change Type	Action	Version Impact
New endpoint	Add to current version	Same version
New optional field	Add to current version	Same version
Remove endpoint	Create new version	New major version
Change field type	Create new version	New major version
Change field name	Create new version	New major version
Remove required field	Create new version	New major version
Add required field	Create new version	New major version
Change error format	Create new version	New major version
Performance improvement	Add to current version	Same version
Bug fix	Add to current version	Same version

Testing

Running Version Tests

cd veza-backend-api
go test ./internal/api/... -v

Test Coverage

• ✅ Version manager functionality
• ✅ Version middleware
• ✅ Header-based versioning
• ✅ URL path versioning
• ✅ Deprecated version handling
• ✅ Version info endpoint

References

• REST API Versioning Best Practices
• API Versioning Strategies
• Semantic Versioning
• RFC 7231 - HTTP/1.1 Semantics

Maintenance

This strategy should be reviewed and updated:

• When creating a new major version
• When deprecating a version
• When changing versioning approach
• Annually for best practices updates

---

Last Updated: 2025-12-25
Maintained By: Veza Backend Team
Related Documents:

• veza-backend-api/docs/API_VERSIONING.md - Technical implementation details
• OPENAPI_MAINTENANCE_GUIDE.md - API documentation maintenance