src/lib/api-versioning/ ├── index.ts # Main exports ├── types.ts # Core type definitions ├── constants.ts # System constants ├── core/ # Core versioning engines │ ├── semantic-version.ts # Semantic version parsing and comparison │ ├── compatibility-engine.ts # Compatibility analysis engine │ └── evolution-engine.ts # API evolution and migration engine ├── graphql/ # GraphQL versioning support │ ├── schema-evolution.ts # Schema evolution and field versioning │ ├── version-resolver.ts # Version-aware GraphQL resolvers │ └── federation-versioning.ts # Apollo Federation versioning ├── rest/ # REST API versioning │ ├── content-negotiation.ts # Content negotiation engine │ ├── version-middleware.ts # Express/Next.js middleware │ └── route-versioning.ts # Route-based versioning ├── testing/ # Testing frameworks │ ├── contract-testing.ts # PACT-style contract testing │ ├── compatibility-matrix.ts # Compatibility testing matrix │ └── version-validator.ts # Version validation tools ├── deployment/ # Deployment strategies │ ├── zero-downtime.ts # Zero-downtime deployment engine │ ├── canary-versioning.ts # Canary deployment strategies │ └── rollback-manager.ts # Automated rollback management ├── analytics/ # Analytics and tracking │ ├── version-tracking.ts # Version usage tracking │ ├── usage-metrics.ts # Usage analytics collection │ └── compatibility-insights.ts # Compatibility analysis ├── documentation/ # Auto-documentation │ ├── auto-versioning.ts # Automatic API documentation versioning │ ├── changelog-generator.ts # Automated changelog generation │ └── migration-guides.ts # Migration guide generation └── client/ # Client SDK support ├── sdk-generator.ts # Multi-language SDK generation ├── version-negotiator.ts # Client version negotiation └── auto-updater.ts # Automatic client updates src/middleware/versioning/ ├── api-version-middleware.ts # Next.js API versioning middleware └── request-router.ts # Request routing based on version src/tools/version-migration/ ├── migration-assistant.ts # Interactive migration assistant ├── compatibility-checker.ts # Version compatibility checker └── rollback-tool.ts # Migration rollback tool docs/api-versioning/ ├── README.md # This file ├── quick-start.md # Getting started guide ├── advanced-usage.md # Advanced configuration and usage ├── migration-guide.md # Migration between versions ├── best-practices.md # API versioning best practices ├── examples/ # Usage examples └── api-reference/ # Detailed API documentation ## Quick Start ### 1. Basic Setup typescript import { SemanticVersionEngine, ContentNegotiationEngine, ApiVersionMiddleware } from '@/lib/api-versioning'; // Configure versioning middleware const versionConfig = { enabled: true, defaultVersion: '1.0.0', supportedVersions: ['1.0.0', '1.1.0', '2.0.0'], routeMapping: { '/api/users': { supportedVersions: ['1.0.0', '2.0.0'], defaultVersion: '2.0.0', deprecationWarnings: true } }, fallbackHandling: 'error', enableMetrics: true, enableCaching: true }; const middleware = new ApiVersionMiddleware(versionConfig); ### 2. REST API Versioning typescript // Content negotiation setup const negotiationConfig = { defaultVersion: '2.0.0', supportedVersions: ['1.0.0', '1.1.0', '2.0.0'], deprecatedVersions: { '1.0.0': { version: '1.0.0', date: new Date('2024-01-01'), reason: 'Legacy version', replacement: '2.0.0' } }, versionAliases: { 'latest': '2.0.0', 'stable': '1.1.0' }, formatTransformers: { 'json': { transform: async (data, version) => transformToVersion(data, version), contentType: 'application/json' } } }; const negotiator = new ContentNegotiationEngine(negotiationConfig); // In your API route export async function GET(request: NextRequest) { const versionRequest = negotiator.negotiateVersion(request); const data = await fetchData(); const versionedResponse = await negotiator.createVersionedResponse( data, versionRequest, '/api/users' ); return negotiator.createHttpResponse(versionedResponse); } ### 3. GraphQL Schema Evolution typescript import { SchemaEvolutionEngine } from '@/lib/api-versioning/graphql'; const evolution = new SchemaEvolutionEngine(); // Register schema versions evolution.registerSchema('1.0.0', schema_v1, versioning_v1); evolution.registerSchema('2.0.0', schema_v2, versioning_v2); // Generate versioned SDL const versionedSchema = evolution.generateVersionedSDL('2.0.0'); // Create version-aware resolvers const versionedResolvers = evolution.createVersionedResolvers('2.0.0', baseResolvers); ### 4. Migration Assistant typescript import { MigrationAssistant } from '@/tools/version-migration'; const assistant = new MigrationAssistant(); // Create migration plan const plan = await assistant.createMigrationPlan({ fromVersion: '1.0.0', toVersion: '2.0.0', clientId: 'my-app', environment: 'staging', dryRun: false }); // Execute migration const session = await assistant.startMigration(plan); // Execute steps interactively while (session.status === 'running') { const result = await assistant.executeNextStep(session.id); console.log(`Step ${result.stepId}: ${result.success ? 'Success' : 'Failed'}`); } ## Configuration ### Environment Variables bash # API Versioning Configuration API_VERSIONING_ENABLED=true API_VERSIONING_DEFAULT_VERSION=2.0.0 API_VERSIONING_CACHE_TTL=300 API_VERSIONING_ANALYTICS_ENABLED=true API_VERSIONING_MIGRATION_TIMEOUT=300000 # Deployment Configuration DEPLOYMENT_STRATEGY=canary CANARY_WEIGHT=10 HEALTH_CHECK_INTERVAL=30 ROLLBACK_ERROR_THRESHOLD=0.05 # Analytics Configuration ANALYTICS_RETENTION_DAYS=365 ANALYTICS_SAMPLING_RATE=1.0 ANALYTICS_REALTIME_ENABLED=true ### Next.js Configuration Add to your next.config.js: javascript /** @type {import('next').NextConfig} */ const nextConfig = { experimental: { middleware: true }, // API versioning middleware configuration async middleware(request) { const { pathname } = request.nextUrl; // Apply versioning middleware to API routes if (pathname.startsWith('/api/')) { const middleware = await import('@/middleware/versioning/api-version-middleware'); return middleware.apiVersionMiddleware(request); } } }; module.exports = nextConfig; ## Monitoring & Analytics ### Version Usage Analytics typescript import { VersionTrackingEngine } from '@/lib/api-versioning/analytics'; const tracker = new VersionTrackingEngine({ enableTracking: true, retentionDays: 90, samplingRate: 1.0, aggregationInterval: 5, enableRealtime: true }); // Track API requests tracker.trackRequest('2.0.0', '/api/users', 'GET', 'client-123'); // Generate analytics report const report = await tracker.generateAnalyticsReport( new Date('2024-01-01'), new Date('2024-02-01') ); ### Compatibility Monitoring typescript import { CompatibilityEngine } from '@/lib/api-versioning/core'; const compatibility = new CompatibilityEngine(); // Generate compatibility matrix const matrix = await compatibility.generateCompatibilityMatrix([ '1.0.0', '1.1.0', '2.0.0' ]); // Check specific version compatibility const status = await compatibility.checkCompatibility('1.0.0', '2.0.0'); console.log(`Compatible: ${status.compatible}, Issues: ${status.issues.length}`); ## Deployment Strategies ### Zero-Downtime Deployment typescript import { ZeroDowntimeDeployment } from '@/lib/api-versioning/deployment'; const deployment = new ZeroDowntimeDeployment(); // Blue-Green Deployment const metrics = await deployment.executeBlueGreenDeployment( '1.0.0', '2.0.0', { healthChecks: [ { type: 'http', endpoint: '/health', interval: 30, successThreshold: 3 } ] } ); // Canary Deployment const canaryMetrics = await deployment.executeCanaryDeployment( '1.0.0', '2.0.0', { canaryWeight: 10, rolloutDuration: 30 } ); ## Testing ### Contract Testing typescript import { ContractTestingEngine } from '@/lib/api-versioning/testing'; const contractTesting = new ContractTestingEngine(); // Register consumer-provider contract const contract = { consumer: 'web-app', provider: 'api-service', version: '2.0.0', interactions: [ { description: 'Get user by ID', request: { method: 'GET', path: '/api/users/123' }, response: { status: 200, body: { id: 123, name: 'John Doe' } } } ] }; contractTesting.registerContract(contract); // Verify provider against contracts const results = await contractTesting.verifyProvider( 'api-service', '2.0.0', 'http://localhost:3000' ); ## Best Practices ### Version Strategy 1. Semantic Versioning: Use semantic versioning (MAJOR.MINOR.PATCH) 2. Backward Compatibility: Maintain backward compatibility within major versions 3. Deprecation Policy: Provide 90-day deprecation notices 4. Documentation: Auto-generate and version API documentation ### Migration Strategy 1. Phased Rollouts: Use canary deployments for major version changes 2. Client Support: Provide multiple version support during transitions 3. Monitoring: Monitor version adoption and error rates 4. Rollback Plans: Always have automated rollback procedures ### Testing Strategy 1. Contract Testing: Use consumer-driven contract testing 2. Compatibility Matrix: Test all supported version combinations 3. Performance Testing: Validate performance across versions 4. End-to-End Testing: Test complete user workflows ## API Reference ### Core Classes - SemanticVersionEngine: Version parsing, comparison, and compatibility - EvolutionEngine: API evolution analysis and migration planning - CompatibilityEngine: Version compatibility analysis - SchemaEvolutionEngine: GraphQL schema evolution and versioning - ContentNegotiationEngine: REST API content negotiation - ZeroDowntimeDeployment: Deployment strategies and orchestration - VersionTrackingEngine: Analytics and usage tracking - MigrationAssistant: Interactive migration guidance ### Middleware - ApiVersionMiddleware: Next.js API versioning middleware - GraphQLVersioningMiddleware: GraphQL versioning middleware ### Tools - Migration Assistant: Interactive migration planning and execution - Compatibility Checker: Version compatibility validation - Analytics Dashboard: Version usage analytics and insights ## Contributing 1. Fork the repository 2. Create a feature branch 3. Add comprehensive tests 4. Update documentation 5. Submit a pull request ## License This project is licensed under the MIT License - see the LICENSE file for details. ## Support For questions, issues, or feature requests: 1. Check the documentation in /docs/api-versioning/ 2. Review examples in /docs/api-versioning/examples/ 3. Open an issue on GitHub 4. Contact the development team --- Built with for enterprise-grade API versioning