1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

// Automated breaking change detection in CI
interface SchemaChange {
  path: string;
  changeType: 'added' | 'removed' | 'modified';
  breaking: boolean;
  description: string;
}
 
function analyzeSchemaChanges(
  oldSchema: OpenAPISchema,
  newSchema: OpenAPISchema
): SchemaChange[] {
  const changes: SchemaChange[] = [];
 
  // Check for removed paths (breaking)
  for (const path of Object.keys(oldSchema.paths || {})) {
    if (!newSchema.paths?.[path]) {
      changes.push({
        path,
        changeType: 'removed',
        breaking: true,
        description: `Endpoint ${path} was removed`,
      });
    }
  }
 
  // Check for removed response fields (breaking)
  for (const [path, pathItem] of Object.entries(oldSchema.paths || {})) {
    for (const [method, operation] of Object.entries(pathItem)) {
      const oldFields = extractResponseFields(operation);
      const newOperation = newSchema.paths?.[path]?.[method];
      const newFields = newOperation ? extractResponseFields(newOperation) : new Set();
 
      for (const field of oldFields) {
        if (!newFields.has(field)) {
          changes.push({
            path: `${path}.${method}.response.${field}`,
            changeType: 'removed',
            breaking: true,
            description: `Response field '${field}' was removed`,
          });
        }
      }
    }
  }
 
  // Check for new required request parameters (breaking)
  for (const [path, pathItem] of Object.entries(newSchema.paths || {})) {
    for (const [method, operation] of Object.entries(pathItem)) {
      const oldOperation = oldSchema.paths?.[path]?.[method];
      
      for (const param of operation.parameters || []) {
        if (param.required) {
          const existedBefore = oldOperation?.parameters?.some(
            p => p.name === param.name
          );
          if (!existedBefore) {
            changes.push({
              path: `${path}.${method}.parameters.${param.name}`,
              changeType: 'added',
              breaking: true,
              description: `Required parameter '${param.name}' was added`,
            });
          }
        }
      }
    }
  }
 
  // Check for type changes (breaking)
  // ... additional checks for field type modifications
 
  return changes;
}
 
// CI pipeline integration
async function checkBackwardCompatibility(): Promise<void> {
  const mainBranchSchema = await fetchSchemaFromBranch('main');
  const currentSchema = await loadCurrentSchema();
  
  const changes = analyzeSchemaChanges(mainBranchSchema, currentSchema);
  const breakingChanges = changes.filter(c => c.breaking);
  
  if (breakingChanges.length > 0) {
    console.error('❌ Breaking changes detected:');
    breakingChanges.forEach(c => {
      console.error(`  - ${c.path}: ${c.description}`);
    });
    console.error('\nTo proceed, either:');
    console.error('  1. Make the changes backward-compatible');
    console.error('  2. Create a new API version (v2)');
    console.error('  3. Add breaking-change-approved label (requires tech lead)');
    process.exit(1);
  }
  
  console.log('✅ No breaking changes detected');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

// Single service handling multiple API versions
import express from 'express';
 
const app = express();
 
// Version extraction middleware
function extractVersion(req: express.Request): number {
  // From URL path: /v2/orders/123 → 2
  const pathMatch = req.path.match(/^\/v(\d+)\//);
  if (pathMatch) return parseInt(pathMatch[1]);
  
  // From header: Api-Version: 2
  const headerVersion = req.get('Api-Version');
  if (headerVersion) return parseInt(headerVersion);
  
  // Default to latest stable
  return 2;
}
 
// Shared business logic
async function getOrderById(orderId: string): Promise<OrderEntity> {
  return orderRepository.findById(orderId);
}
 
// Version-specific response formatting
function formatOrderResponse(order: OrderEntity, version: number): object {
  switch (version) {
    case 1:
      // V1: Legacy format with deprecated fields
      return {
        id: order.id,
        customer_id: order.customerId, // snake_case in v1
        items: order.items.map(item => ({
          product_id: item.productId,
          qty: item.quantity,  // 'qty' in v1, 'quantity' in v2
          price: item.price,
        })),
        total: order.total,
        status: order.status.toLowerCase(), // lowercase in v1
        created: order.createdAt.toISOString(),
      };
      
    case 2:
      // V2: Current format with camelCase
      return {
        id: order.id,
        customerId: order.customerId,
        items: order.items.map(item => ({
          productId: item.productId,
          quantity: item.quantity,
          unitPrice: item.price,
          lineTotal: item.quantity * item.price,
        })),
        total: order.total,
        currency: order.currency,  // New in v2
        status: order.status,
        statusHistory: order.statusHistory,  // New in v2
        createdAt: order.createdAt.toISOString(),
        updatedAt: order.updatedAt.toISOString(),  // New in v2
      };
      
    default:
      throw new Error(`Unsupported API version: ${version}`);
  }
}
 
// Version-specific request parsing
function parseCreateOrderRequest(
  body: unknown,
  version: number
): CreateOrderInput {
  switch (version) {
    case 1:
      // V1: snake_case, no idempotency key
      const v1Body = body as V1CreateOrderBody;
      return {
        customerId: v1Body.customer_id,
        items: v1Body.items.map(item => ({
          productId: item.product_id,
          quantity: item.qty,
        })),
      };
      
    case 2:
      // V2: camelCase, requires idempotency key
      const v2Body = body as V2CreateOrderBody;
      if (!v2Body.idempotencyKey) {
        throw new ValidationError('idempotencyKey is required in v2');
      }
      return {
        customerId: v2Body.customerId,
        items: v2Body.items,
        idempotencyKey: v2Body.idempotencyKey,
      };
      
    default:
      throw new Error(`Unsupported API version: ${version}`);
  }
}
 
// Routes for both versions
app.get(['/v1/orders/:id', '/v2/orders/:id'], async (req, res) => {
  const version = extractVersion(req);
  const order = await getOrderById(req.params.id);
  
  if (!order) {
    return res.status(404).json({ error: 'Order not found' });
  }
  
  res.json(formatOrderResponse(order, version));
});
 
app.post(['/v1/orders', '/v2/orders'], async (req, res) => {
  const version = extractVersion(req);
  
  try {
    const input = parseCreateOrderRequest(req.body, version);
    const order = await createOrder(input);
    res.status(201).json(formatOrderResponse(order, version));
  } catch (error) {
    if (error instanceof ValidationError) {
      return res.status(400).json({ error: error.message });
    }
    throw error;
  }
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

// Deprecation middleware with standard headers
interface DeprecationConfig {
  version: string;
  deprecatedDate: Date;
  sunsetDate: Date;
  migrationGuide: string;
  replacedBy?: string;
}
 
const deprecatedVersions: Record<string, DeprecationConfig> = {
  'v1': {
    version: 'v1',
    deprecatedDate: new Date('2024-01-15'),
    sunsetDate: new Date('2024-06-15'),
    migrationGuide: 'https://docs.company.com/api/migration/v1-to-v2',
    replacedBy: 'v2',
  },
};
 
function deprecationMiddleware(
  req: express.Request,
  res: express.Response,
  next: express.NextFunction
): void {
  const version = extractVersion(req);
  const config = deprecatedVersions[`v${version}`];
  
  if (!config) {
    return next();
  }
 
  const now = new Date();
  
  // Check if past sunset date
  if (now >= config.sunsetDate) {
    res.status(410).json({
      error: 'GONE',
      message: `API version ${config.version} has been sunset as of ${config.sunsetDate.toISOString()}`,
      migrationGuide: config.migrationGuide,
      replacedBy: config.replacedBy,
    });
    return;
  }
 
  // Add deprecation headers (RFC 8594)
  res.set('Deprecation', config.deprecatedDate.toISOString());
  res.set('Sunset', config.sunsetDate.toISOString());
  res.set('Link', `<${config.migrationGuide}>; rel="deprecation"`);
  
  if (config.replacedBy) {
    res.set('Link', `</${config.replacedBy}/${req.path}>; rel="successor-version"`);
  }
 
  // Custom header for programmatic detection
  res.set('X-API-Deprecated', 'true');
  res.set('X-API-Sunset-Date', config.sunsetDate.toISOString());
 
  // Log usage for tracking
  logDeprecatedUsage({
    version: config.version,
    endpoint: req.path,
    method: req.method,
    clientId: extractClientId(req),
    timestamp: now,
  });
 
  // Warning in response body for non-HEAD requests
  const originalJson = res.json.bind(res);
  res.json = (body: unknown) => {
    if (typeof body === 'object' && body !== null) {
      return originalJson({
        ...body,
        _deprecation: {
          warning: `This API version is deprecated and will be removed on ${config.sunsetDate.toDateString()}`,
          migrationGuide: config.migrationGuide,
          sunsetDate: config.sunsetDate.toISOString(),
        },
      });
    }
    return originalJson(body);
  };
 
  next();
}
 
// Consumer tracking for targeted outreach
async function getDeprecatedVersionUsage(): Promise<DeprecatedUsageReport> {
  const usage = await analyticsService.query({
    metric: 'api_requests',
    filter: { deprecated: true },
    groupBy: ['version', 'clientId', 'endpoint'],
    range: '30d',
  });
 
  return {
    byVersion: aggregateByVersion(usage),
    byClient: aggregateByClient(usage),
    topEndpoints: getTopEndpoints(usage),
    migrationProgress: calculateMigrationProgress(usage),
  };
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

// Event versioning with explicit schema versions
interface VersionedEvent {
  eventId: string;
  eventType: string;
  schemaVersion: number;
  timestamp: Date;
  payload: unknown;
}
 
// Event schema registry (in-memory example)
const eventSchemas: Record<string, Record<number, EventSchema>> = {
  'OrderPlaced': {
    1: {
      version: 1,
      fields: ['orderId', 'customerId', 'items', 'total'],
    },
    2: {
      version: 2,
      fields: ['orderId', 'customerId', 'items', 'total', 'currency', 'channel'],
      // New fields in v2
    },
  },
};
 
// Producer: Always publishes latest version
function publishOrderPlacedEvent(order: Order): VersionedEvent {
  return {
    eventId: crypto.randomUUID(),
    eventType: 'OrderPlaced',
    schemaVersion: 2,  // Always latest
    timestamp: new Date(),
    payload: {
      orderId: order.id,
      customerId: order.customerId,
      items: order.items,
      total: order.total,
      currency: order.currency,  // v2 field
      channel: order.channel,    // v2 field
    },
  };
}
 
// Consumer: Handles multiple versions
class OrderEventHandler {
  async handle(event: VersionedEvent): Promise<void> {
    if (event.eventType !== 'OrderPlaced') return;
    
    // Normalize to latest version
    const normalizedPayload = this.normalizeToV2(event);
    
    // Process with normalized data
    await this.processOrderPlaced(normalizedPayload);
  }
  
  private normalizeToV2(event: VersionedEvent): OrderPlacedV2Payload {
    switch (event.schemaVersion) {
      case 1:
        // Upgrade v1 to v2 with defaults
        const v1 = event.payload as OrderPlacedV1Payload;
        return {
          orderId: v1.orderId,
          customerId: v1.customerId,
          items: v1.items,
          total: v1.total,
          currency: 'USD',     // Default for v1 events
          channel: 'unknown',  // Default for v1 events
        };
        
      case 2:
        return event.payload as OrderPlacedV2Payload;
        
      default:
        throw new Error(`Unknown schema version: ${event.schemaVersion}`);
    }
  }
}
 
// Schema registry integration (e.g., Confluent)
class SchemaRegistryClient {
  async registerSchema(
    subject: string,
    schema: object
  ): Promise<{ id: number }> {
    // POST to schema registry
    const response = await fetch(`${this.baseUrl}/subjects/${subject}/versions`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ schema: JSON.stringify(schema) }),
    });
    return response.json();
  }
  
  async checkCompatibility(
    subject: string,
    schema: object
  ): Promise<{ compatible: boolean }> {
    // POST to compatibility check endpoint
    const response = await fetch(
      `${this.baseUrl}/compatibility/subjects/${subject}/versions/latest`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ schema: JSON.stringify(schema) }),
      }
    );
    return response.json();
  }
}