# 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)

```bash
# Get tracks
GET /api/v1/tracks

# Create playlist
POST /api/v1/playlists
```

### Future (v2)

```bash
# 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:

```go
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:

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

## References

- [REST API Versioning Best Practices](https://restfulapi.net/versioning/)
- [API Versioning Strategies](https://www.baeldung.com/rest-versioning)
- See `API_VERSIONING_STRATEGY.md` for comprehensive strategy document

---

**Last Updated**: 2025-12-25  
**Maintained By**: Veza Backend Team  
**Related Documents**: 
- `API_VERSIONING_STRATEGY.md` - Comprehensive versioning strategy