Update documentation with last updated dates and improve navigation indexes
- 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.
This commit is contained in:
defiQUG
189
docs/api/API_VERSIONING.md
Normal file
189
docs/api/API_VERSIONING.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# 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)
|
||||
|
||||
Reference in New Issue
Block a user