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

## References

- [REST API Versioning Best Practices](https://restfulapi.net/versioning/)
- [API Versioning Strategies](https://www.baeldung.com/rest-versioning)

---

**Last Updated**: 2025-01-27  
**Maintained By**: Veza Backend Team