Sankofa/docs/api/API_VERSIONING.md

# 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. The Phoenix API Railing (Infra, VE, Health, tenant-scoped) uses `/api/v1/` and aligns with this strategy.

```
/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)