4952ecf453
- Added "Last Updated" date to multiple documentation files for better tracking. - Enhanced the README with quick navigation indexes for guides, references, and architecture documentation. - Updated titles in Keycloak deployment and testing guide for consistency.
190 lines
4.3 KiB
Markdown
190 lines
4.3 KiB
Markdown
# API Versioning Guide
|
|
|
|
**Last Updated**: 2025-01-09
|
|
|
|
## Overview
|
|
|
|
This document describes the API versioning strategy for the Sankofa Phoenix API.
|
|
|
|
## Versioning Strategy
|
|
|
|
### URL-Based Versioning
|
|
|
|
The API uses URL-based versioning for REST endpoints:
|
|
|
|
```
|
|
/api/v1/resource
|
|
/api/v2/resource
|
|
```
|
|
|
|
### GraphQL Versioning
|
|
|
|
GraphQL APIs use schema evolution rather than versioning:
|
|
- **Schema Evolution**: Additive changes only
|
|
- **Deprecation**: Fields are deprecated before removal
|
|
- **Schema Introspection**: Clients can query schema version
|
|
|
|
## Version Numbering
|
|
|
|
### Semantic Versioning
|
|
|
|
API versions follow semantic versioning (semver):
|
|
- **Major (v1, v2)**: Breaking changes
|
|
- **Minor (v1.1, v1.2)**: New features, backward compatible
|
|
- **Patch (v1.1.1, v1.1.2)**: Bug fixes, backward compatible
|
|
|
|
### Version Lifecycle
|
|
|
|
1. **Current Version**: Latest stable version (e.g., v1)
|
|
2. **Supported Versions**: Previous major version (e.g., v1 if v2 is current)
|
|
3. **Deprecated Versions**: Announcement period before removal (6 months minimum)
|
|
4. **Removed Versions**: No longer available
|
|
|
|
## Breaking Changes
|
|
|
|
### What Constitutes a Breaking Change
|
|
|
|
- Removing an endpoint
|
|
- Removing a required field
|
|
- Changing field types
|
|
- Changing authentication requirements
|
|
- Changing response formats significantly
|
|
|
|
### Breaking Change Process
|
|
|
|
1. **Deprecation Notice**: Announce deprecation 6 months in advance
|
|
2. **Documentation**: Update documentation with migration guide
|
|
3. **Deprecated Version**: Maintain deprecated version for transition period
|
|
4. **Removal**: Remove after deprecation period
|
|
|
|
## Non-Breaking Changes
|
|
|
|
### Safe Changes
|
|
|
|
- Adding new endpoints
|
|
- Adding optional fields
|
|
- Adding new response fields
|
|
- Performance improvements
|
|
- Bug fixes (that don't change behavior)
|
|
|
|
## GraphQL Schema Evolution
|
|
|
|
### Additive Changes
|
|
|
|
GraphQL schemas evolve additively:
|
|
|
|
```graphql
|
|
# Adding a new field is safe
|
|
type User {
|
|
id: ID!
|
|
email: String!
|
|
name: String
|
|
createdAt: DateTime # New field - safe
|
|
}
|
|
|
|
# Deprecating a field before removal
|
|
type User {
|
|
id: ID!
|
|
email: String! @deprecated(reason: "Use username instead")
|
|
username: String # New field replacing email
|
|
}
|
|
```
|
|
|
|
### Deprecation Process
|
|
|
|
1. **Mark as Deprecated**: Use `@deprecated` directive
|
|
2. **Maintain Support**: Continue supporting deprecated fields
|
|
3. **Document Migration**: Provide migration guide
|
|
4. **Remove**: Remove after sufficient notice period
|
|
|
|
## Migration Guides
|
|
|
|
### Version Migration
|
|
|
|
When migrating between versions:
|
|
|
|
1. **Review Changelog**: Check what changed
|
|
2. **Update Client Code**: Update to use new endpoints/fields
|
|
3. **Test Thoroughly**: Test all affected functionality
|
|
4. **Deploy**: Deploy updated client code
|
|
5. **Monitor**: Monitor for issues
|
|
|
|
### Example Migration: v1 to v2
|
|
|
|
```bash
|
|
# Old v1 endpoint
|
|
GET /api/v1/users
|
|
|
|
# New v2 endpoint
|
|
GET /api/v2/users
|
|
# Changes: pagination now required, response format updated
|
|
```
|
|
|
|
## Version Detection
|
|
|
|
### HTTP Headers
|
|
|
|
API version information in response headers:
|
|
|
|
```
|
|
X-API-Version: 1.2.3
|
|
X-Deprecated-Version: false
|
|
```
|
|
|
|
### Schema Introspection (GraphQL)
|
|
|
|
Query schema version information:
|
|
|
|
```graphql
|
|
query {
|
|
__schema {
|
|
queryType {
|
|
description # May contain version info
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### For API Consumers
|
|
|
|
1. **Pin Versions**: Use specific API versions in production
|
|
2. **Monitor Deprecations**: Watch for deprecation notices
|
|
3. **Plan Migrations**: Allow time for version migrations
|
|
4. **Test Thoroughly**: Test after version updates
|
|
|
|
### For API Developers
|
|
|
|
1. **Minimize Breaking Changes**: Prefer additive changes
|
|
2. **Provide Migration Guides**: Document all breaking changes
|
|
3. **Maintain Deprecated Versions**: Support for transition period
|
|
4. **Version Documentation**: Keep version-specific documentation
|
|
5. **Clear Changelogs**: Document all version changes
|
|
|
|
## Current Versions
|
|
|
|
### REST API
|
|
- **Current**: v1
|
|
- **Status**: Stable
|
|
|
|
### GraphQL API
|
|
- **Current Schema**: 1.0
|
|
- **Status**: Stable
|
|
- **Deprecations**: None currently
|
|
|
|
## Support Policy
|
|
|
|
- **Current Version**: Full support
|
|
- **Previous Major Version**: Full support (minimum 12 months)
|
|
- **Deprecated Versions**: Security fixes only
|
|
- **Removed Versions**: No support
|
|
|
|
---
|
|
|
|
**Related Documentation:**
|
|
- [API Documentation](./API_DOCUMENTATION.md)
|
|
- [API Contracts](./API_CONTRACTS.md)
|
|
- [API Examples](./examples.md)
|
|
|