senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/veza-backend-api/docs/API_VERSIONING.md

3.4 KiB
Raw Blame History

API Versioning Strategy

Overview

This document describes the API versioning strategy for Veza Backend API.

Current Version: v1
Status: Active

Versioning Approach

URL Path Versioning

The API uses URL path versioning where the version is included in the path:

/api/v1/tracks
/api/v1/playlists
/api/v1/auth/login

Version Format

  • Format: v{major}
  • Examples: v1, v2, v3
  • Major versions indicate breaking changes

Version Lifecycle

v1 (Current)

  • Status: Active
  • Deprecation Date: TBD
  • End of Life: TBD
  • Breaking Changes: None planned

Future Versions

When introducing a new version (e.g., v2):

  1. Announcement: Announce deprecation of v1 at least 6 months in advance
  2. Parallel Support: Support both v1 and v2 simultaneously
  3. Migration Guide: Provide migration guide from v1 to v2
  4. Deprecation: Mark v1 as deprecated but keep it functional
  5. End of Life: Remove v1 after deprecation period (minimum 12 months)

Breaking Changes

Breaking changes require a new major version:

  • Removed endpoints
  • Changed request/response formats
  • Changed authentication mechanisms
  • Changed error response formats
  • Removed required fields
  • Changed field types

Non-Breaking Changes

These changes can be made within the same version:

  • New endpoints
  • New optional fields in requests/responses
  • New error codes
  • Performance improvements
  • Bug fixes

Version Headers

Clients can specify the API version using headers (future enhancement):

Accept: application/vnd.veza.v1+json

Currently, only URL path versioning is supported.

Migration Strategy

For API Consumers

  1. Monitor deprecation notices
  2. Test new versions in staging environment
  3. Migrate to new version before end of life
  4. Use migration guides provided

For API Developers

  1. Document all breaking changes
  2. Provide migration guides
  3. Maintain backward compatibility during deprecation period
  4. Test both versions in CI/CD

Examples

Current (v1)

# Get tracks
GET /api/v1/tracks

# Create playlist
POST /api/v1/playlists

Future (v2)

# Get tracks (new version)
GET /api/v2/tracks

# Create playlist (new version)
POST /api/v2/playlists

Implementation Details

Version Manager

The API uses a VersionManager to handle version registration and validation:

vm := NewVersionManager(logger)
vm.RegisterVersion(&APIVersion{
    Version:     "v1",
    Deprecated:  false,
    Description: "Current stable API version",
})

Version Middleware

The VersionMiddleware extracts the version from:

  1. X-API-Version header
  2. Accept header (application/vnd.veza.v1+json)
  3. URL path (/api/v1/...)

Version Context

The version is stored in the Gin context and can be accessed:

version := GetAPIVersion(c)  // Returns "v1", "v2", etc.
versionInfo := GetAPIVersionInfo(c)  // Returns full APIVersion struct

References

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

  • API_VERSIONING_STRATEGY.md - Comprehensive versioning strategy