Manage Api Versions

Implement comprehensive API versioning strategies with backward compatibility, smooth migration paths, deprecation workflows, and automated compatibility testing to ensure seamless API evolution.

When to Use This Command

Use /manage-api-versions when you need to:

• Introduce breaking changes without disrupting existing clients
• Support multiple API versions simultaneously
• Provide smooth migration paths for API consumers
• Implement deprecation strategies with clear timelines
• Maintain backward compatibility while innovating
• Comply with enterprise SLA requirements

DON'T use this when:

• Building internal-only APIs with controlled clients (coordinate directly)
• API is in early beta with no production users (iterate freely)
• Changes are purely additive and backward compatible (versioning unnecessary)

Design Decisions

This command implements URL Path Versioning + Accept Header as the primary approach because:

• Most intuitive for developers (visible in URL)
• Easy to route and cache at infrastructure level
• Clear version separation in code organization
• Accept headers provide fine-grained control
• Works well with API gateways and CDNs
• Industry standard for REST APIs

Alternative considered: Header-Only Versioning

• Cleaner URLs
• More RESTful approach
• Harder to test and debug
• Recommended for purist REST APIs

Alternative considered: Query Parameter Versioning

• Easy to implement
• Optional versioning support
• Can pollute URL structure
• Recommended for simple versioning needs

Prerequisites

Before running this command:

1. Define versioning strategy and policy
2. Identify breaking vs. non-breaking changes
3. Plan deprecation timeline (typically 6-12 months)
4. Set up monitoring for version usage
5. Prepare migration documentation

Implementation Process

Step 1: Choose Versioning Strategy

Select and implement the appropriate versioning mechanism for your API architecture.

Step 2: Create Version Infrastructure

Set up routing, middleware, and transformers for multi-version support.

Step 3: Implement Compatibility Layer

Build backward compatibility adapters and response transformers.

Step 4: Add Deprecation Workflow

Implement deprecation notices, sunset headers, and migration tools.

Step 5: Set Up Version Testing

Create comprehensive test suites covering all supported versions.

Output Format

The command generates:

• api/v1/ - Version 1 implementation
• api/v2/ - Version 2 implementation
• middleware/version-router.js - Version routing logic
• transformers/ - Version-specific data transformers
• tests/compatibility/ - Cross-version compatibility tests
• docs/migration-guide.md - Version migration documentation

Code Examples

Example 1: Comprehensive URL Path Versioning System

// middleware/version-router.js
const express = require('express');
const semver = require('semver');

class APIVersionManager {
  constructor(options = {}) {
    this.versions = new Map();
    this.defaultVersion = options.defaultVersion || 'v1';
    this.deprecationPolicy = options.deprecationPolicy || {
      warningPeriod: 90,  // days before sunset
      sunsetPeriod: 180   // days until removal
    };
    this.versionInfo = new Map();
  }

  registerVersion(version, router, metadata = {}) {
    this.versions.set(version, router);
    this.versionInfo.set(version, {
…

Example 2: Advanced Content Negotiation Versioning

// middleware/content-negotiation.js
const accepts = require('accepts');

class ContentNegotiationVersioning {
  constructor() {
    this.handlers = new Map();
    this.transformers = new Map();
  }

  register(version, mediaType, handler, transformer = null) {
    const key = `${version}:${mediaType}`;
    this.handlers.set(key, handler);

    if (transformer) {
      this.transformers.set(key, transformer);
    }
  }
…

Example 3: Automated Version Testing and Documentation

// tests/version-compatibility.test.js
const request = require('supertest');
const app = require('../app');

class VersionCompatibilityTester {
  constructor(app) {
    this.app = app;
    this.versions = ['v1', 'v2', 'v3'];
    this.endpoints = [];
    this.results = [];
  }

  addEndpoint(method, path, testCases) {
    this.endpoints.push({ method, path, testCases });
  }

  async runCompatibilityTests() {
    console.log('Running API version compatibility tests...\n');
…

Error Handling

Configuration Options

Versioning Strategies

• url-path: Version in URL path (/v1/)
• header: Version in Accept header
• query: Version in query parameter