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:

# 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

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

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 Contracts
• API Examples