158 lines
3.4 KiB
Markdown
158 lines
3.4 KiB
Markdown
# 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
|