Breaking vs Non-Breaking Changes

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

// Comprehensive Examples of Breaking Changes
 
// ❌ STRUCTURAL BREAKING CHANGES
 
// 1. Removing a field
interface UserV1 { id: string; name: string; email: string; }
interface UserV2 { id: string; email: string; }  // 'name' removed!
 
// 2. Renaming a field  
interface OrderV1 { orderId: string; total: number; }
interface OrderV2 { id: string; amount: number; }  // Fields renamed!
 
// 3. Changing field types
interface ProductV1 { price: number; }    // price: 1999 (cents)
interface ProductV2 { price: string; }    // price: "19.99" (formatted)
 
// 4. Changing from value to object
interface AddressV1 { country: string; }  // country: "US"
interface AddressV2 { country: { code: string; name: string; }; }
 
 
// ❌ SEMANTIC BREAKING CHANGES
 
// 5. Changing enum values
type StatusV1 = 'active' | 'inactive';
type StatusV2 = 'enabled' | 'disabled';  // Same meaning, different values!
 
// 6. Stricter validation
// V1: email can be any string
// V2: email must match RFC 5322
// Previously valid requests now fail!
 
// 7. Changed defaults
// V1: sortOrder defaults to "asc"
// V2: sortOrder defaults to "desc"
// Same request, different results!
 
 
// ❌ BEHAVIORAL BREAKING CHANGES
 
// 8. Changed operation semantics
// V1: DELETE /users/:id soft-deletes (preserves data)
// V2: DELETE /users/:id hard-deletes (removes data)
// Same endpoint, catastrophically different behavior!
 
// 9. Added required authentication
// V1: GET /public/products (no auth)
// V2: GET /public/products (requires API key)
// Existing integrations break!
 
// 10. Changed rate limits
// V1: 1000 requests/minute
// V2: 100 requests/minute
// High-traffic integrations fail!

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

// Examples of Non-Breaking Changes
 
// ✅ ADDITIVE CHANGES (Safe)
 
// 1. Adding new optional fields
interface UserV1 { id: string; email: string; }
interface UserV2 { 
  id: string; 
  email: string; 
  phone?: string;        // New optional field - safe!
  preferences?: object;  // New optional field - safe!
}
 
// 2. Adding new endpoints
// V1: GET /users, POST /users
// V2: GET /users, POST /users, GET /users/:id/activity  // New endpoint - safe!
 
// 3. Adding new optional query parameters
// V1: GET /users?status=active
// V2: GET /users?status=active&sort=name&limit=50  // New params - safe!
 
// 4. Adding new HTTP methods
// V1: GET /reports/:id
// V2: GET /reports/:id, DELETE /reports/:id  // New method - safe!
 
 
// ✅ RELAXED VALIDATION (Safe)
 
// 5. Making required fields optional
interface CreateUserV1 { name: string; email: string; phone: string; }
interface CreateUserV2 { name: string; email: string; phone?: string; }  // Safe!
 
// 6. Accepting additional formats
// V1: date must be "YYYY-MM-DD"
// V2: date accepts "YYYY-MM-DD", ISO 8601, or Unix timestamp
// Existing clients unaffected!
 
// 7. Widening accepted values
// V1: quantity must be 1-100
// V2: quantity must be 1-1000
// Existing valid requests still valid!
 
 
// ✅ PERFORMANCE IMPROVEMENTS (Safe)
 
// 8. Better response times - always safe
// 9. Higher rate limits - always safe
// 10. More efficient pagination - safe if backward compatible
 
 
// ⚠️ CONDITIONALLY SAFE
 
// Adding enum values - safe IF clients handle unknown values
type PaymentStatusV1 = 'pending' | 'completed' | 'failed';
type PaymentStatusV2 = 'pending' | 'completed' | 'failed' | 'refunded';
 
// Safe if client has:
function handleStatus(status: string) {
  switch (status) {
    case 'pending': return 'Waiting...';
    case 'completed': return 'Done!';
    case 'failed': return 'Error';
    default: return 'Unknown status';  // Handles new values gracefully!
  }
}
 
// BREAKS if client has:
function handleStatusBroken(status: PaymentStatusV1) {
  // TypeScript enum exhaustiveness - 'refunded' causes 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

// Deep Dive: The Enum Addition Problem
 
// Scenario: Your API currently returns order status
type OrderStatusV1 = 'pending' | 'processing' | 'shipped' | 'delivered';
 
// You want to add a new status for returns
type OrderStatusV2 = OrderStatusV1 | 'returned';
 
// Why this can break clients:
 
// 1. TypeScript exhaustive switch (compile error in strict mode)
function getStatusMessageBad(status: OrderStatusV1): string {
  switch (status) {
    case 'pending': return 'Waiting for confirmation';
    case 'processing': return 'Being prepared';
    case 'shipped': return 'On the way';
    case 'delivered': return 'Complete';
    // No default - TypeScript ensures all cases handled
    // If 'returned' arrives, this doesn't compile!
  }
}
 
// 2. Serialization/deserialization failures
interface Order {
  id: string;
  status: 'pending' | 'processing' | 'shipped' | 'delivered';  // Strict type
}
 
// Strongly-typed languages may reject unknown values:
// Java: JsonMappingException
// C#: JsonException  
// Go: json: cannot unmarshal
 
// 3. Database constraints
// CREATE TABLE orders (
//   status ENUM('pending', 'processing', 'shipped', 'delivered')
// );
// 'returned' value causes insert failure!
 
 
// Safe patterns for clients:
 
// 1. Always include default case
function getStatusMessageSafe(status: string): string {
  switch (status) {
    case 'pending': return 'Waiting for confirmation';
    case 'processing': return 'Being prepared';
    case 'shipped': return 'On the way';
    case 'delivered': return 'Complete';
    default: return `Status: ${status}`;  // Handle unknown gracefully
  }
}
 
// 2. Use string types with known constants
const ORDER_STATUSES = ['pending', 'processing', 'shipped', 'delivered'] as const;
type OrderStatus = typeof ORDER_STATUSES[number] | string;  // Open for extension
 
// 3. Document unknown value handling in API contract
/**
 * @property status - Order status. New values may be added
 *                    without notice. Clients MUST handle
 *                    unknown values gracefully.
 */

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

// Automated Breaking Change Detection
 
import { compareOpenAPISchemas } from 'openapi-diff';
 
interface BreakingChangeReport {
  breaking: Change[];
  nonBreaking: Change[];
  unknown: Change[];
}
 
interface Change {
  type: 'added' | 'removed' | 'modified';
  path: string;
  description: string;
  severity: 'breaking' | 'warning' | 'info';
}
 
async function detectBreakingChanges(
  currentSchema: OpenAPISpec,
  proposedSchema: OpenAPISpec
): Promise<BreakingChangeReport> {
  const diff = await compareOpenAPISchemas(currentSchema, proposedSchema);
  
  const report: BreakingChangeReport = {
    breaking: [],
    nonBreaking: [],
    unknown: [],
  };
  
  for (const change of diff.changes) {
    if (isBreakingChange(change)) {
      report.breaking.push(formatChange(change, 'breaking'));
    } else if (isNonBreakingChange(change)) {
      report.nonBreaking.push(formatChange(change, 'info'));
    } else {
      report.unknown.push(formatChange(change, 'warning'));
    }
  }
  
  return report;
}
 
function isBreakingChange(change: DiffChange): boolean {
  // Removals are always breaking
  if (change.type === 'removed') return true;
  
  // Type changes are breaking
  if (change.type === 'type-changed') return true;
  
  // Making optional required is breaking
  if (change.type === 'required-added') return true;
  
  // Narrowing validation is breaking
  if (change.type === 'validation-stricter') return true;
  
  return false;
}
 
// CI/CD Integration
async function ciBreakingChangeCheck() {
  const current = await loadSchema('main');
  const proposed = await loadSchema('pr-branch');
  
  const report = await detectBreakingChanges(current, proposed);
  
  if (report.breaking.length > 0) {
    console.error('❌ Breaking changes detected!');
    report.breaking.forEach(c => console.error(`  - ${c.description}`));
    
    // Require explicit acknowledgment
    if (!process.env.BREAKING_CHANGE_ACKNOWLEDGED) {
      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

// Contract Testing for Backward Compatibility
 
// Consumer contract defines what the consumer expects
const consumerContract = {
  name: 'mobile-app-v3.2',
  expectations: [
    {
      description: 'Get user returns expected fields',
      request: { method: 'GET', path: '/users/123' },
      response: {
        status: 200,
        bodyMatches: {
          id: 'string',
          email: 'string',
          name: 'string',  // Consumer expects 'name' field
        },
      },
    },
    {
      description: 'Create order accepts current format',
      request: {
        method: 'POST',
        path: '/orders',
        body: { productId: 'abc', quantity: 2 },  // Current format
      },
      response: {
        status: 201,
        bodyMatches: {
          orderId: 'string',
          status: 'string',
        },
      },
    },
  ],
};
 
// Run contract tests against new API version
async function verifyContract(contract: ConsumerContract): Promise<TestResult[]> {
  const results: TestResult[] = [];
  
  for (const expectation of contract.expectations) {
    const response = await callApi(expectation.request);
    
    const passed = 
      response.status === expectation.response.status &&
      matchesShape(response.body, expectation.response.bodyMatches);
    
    results.push({
      description: expectation.description,
      passed,
      details: passed ? null : {
        expected: expectation.response,
        actual: response,
      },
    });
  }
  
  return results;
}
 
// Pact-style consumer-driven contract testing
// 1. Consumers publish their contracts (expectations)
// 2. Provider runs all consumer contracts before release
// 3. Failing contracts block deployment
// 4. Provides clear visibility into consumer dependencies

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

// Defensive API Design Patterns
 
// 1. EXTENSIBLE ENUMS
// Document explicitly in OpenAPI/JSON Schema
const orderStatusSchema = {
  type: 'string',
  enum: ['pending', 'processing', 'shipped', 'delivered'],
  description: `Order status. WARNING: New values may be added.
                 Clients MUST handle unknown values gracefully.`,
  'x-extensible-enum': true,  // Custom extension for tooling
};
 
 
// 2. CONSISTENT ENVELOPE PATTERN
// Wrap responses in consistent structure with room for evolution
 
interface ApiResponse<T> {
  data: T;                     // The actual payload
  meta?: ResponseMeta;         // Pagination, timing, etc.
  links?: HateoasLinks;        // Navigation links
  warnings?: Warning[];        // Non-fatal issues
}
 
// This envelope can gain new top-level fields without breaking 'data'
interface ResponseMeta {
  requestId: string;
  processingTime: number;
  // Future: add new meta fields here
}
 
// 3. OPTIONAL BY DEFAULT
// Make new fields optional, always
interface User {
  id: string;                  // Required, immutable
  email: string;               // Required, core field
  phone?: string;              // Optional
  preferences?: Preferences;   // Optional (can add fields inside)
  metadata?: Record<string, unknown>;  // Catch-all for custom data
}
 
 
// 4. PRESERVE DEPRECATED FIELDS
// Instead of removing, mark deprecated and return both
 
interface ProductV1 {
  price: number;               // cents - deprecated
}
 
interface ProductV2 {
  price: number;               // Still returned for compatibility
  priceAmount: number;         // Same value, new name
  priceCurrency: string;       // New field for currency
}
 
// Transition period: return both until old clients migrate
 
 
// 5. USE FORWARD-COMPATIBLE VALUE TYPES
// Prefer strings over numbers for IDs (can add prefixes later)
// Prefer ISO dates over custom formats
// Prefer maps over fixed object structures when structure may evolve
 
// Bad: Forces structural change if limits change
interface LimitsV1 {
  maxItems: number;
  maxSize: number;
}
 
// Good: Can add limits without structural change
interface LimitsV2 {
  limits: Record<string, number>;
  // { maxItems: 100, maxSize: 1000, maxConnections: 50 }
}

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

// Request Tolerance Patterns
 
// IGNORE UNKNOWN FIELDS
// Don't reject requests with extra fields
 
function parseCreateUserRequest(body: unknown): CreateUserInput {
  const parsed = body as Record<string, unknown>;
  
  // Extract only known fields, ignore extras
  return {
    name: validateString(parsed.name),
    email: validateEmail(parsed.email),
    // Unknown fields like 'futureField' are silently ignored
  };
}
 
// BAD: Strict parsing that rejects unknown fields
function parseStrictly(body: unknown): CreateUserInput {
  const knownFields = ['name', 'email'];
  for (const key of Object.keys(body)) {
    if (!knownFields.includes(key)) {
      throw new Error(`Unknown field: ${key}`);  // Breaks forward compat!
    }
  }
  // ...
}
 
 
// ACCEPT MULTIPLE FORMATS
// Support common variations of the same value
 
function parseDate(value: unknown): Date {
  if (value instanceof Date) return value;
  if (typeof value === 'number') return new Date(value * 1000);  // Unix
  if (typeof value === 'string') {
    // Try multiple formats
    const iso = Date.parse(value);
    if (!isNaN(iso)) return new Date(iso);
    
    const formats = ['YYYY-MM-DD', 'DD/MM/YYYY', 'MM-DD-YYYY'];
    for (const format of formats) {
      const parsed = parseWithFormat(value, format);
      if (parsed) return parsed;
    }
  }
  throw new Error('Invalid date format');
}
 
 
// CASE-INSENSITIVE ENUMS
// Accept 'ACTIVE', 'active', 'Active' for status values
 
function parseStatus(value: string): Status {
  const normalized = value.toLowerCase();
  const validStatuses = ['active', 'inactive', 'pending'];
  
  if (validStatuses.includes(normalized)) {
    return normalized as Status;
  }
  throw new Error(`Invalid status: ${value}`);
}

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

// Breaking Change Communication System
 
interface BreakingChangeAnnouncement {
  id: string;
  title: string;
  description: string;
  affectedEndpoints: string[];
  currentBehavior: string;
  newBehavior: string;
  reason: string;
  migrationGuide: string;
  timeline: {
    announced: Date;
    newVersionAvailable: Date;
    deprecationStart: Date;
    deprecationEnd: Date;  // Sunset
  };
  impact: 'high' | 'medium' | 'low';
}
 
// Example announcement
const announcement: BreakingChangeAnnouncement = {
  id: 'BC-2024-001',
  title: 'User name field split',
  description: 'The `name` field is being replaced with `firstName` and `lastName`',
  affectedEndpoints: ['GET /users/:id', 'POST /users', 'PATCH /users/:id'],
  currentBehavior: 'User resource has single `name` field',
  newBehavior: 'User resource has `firstName` and `lastName` fields',
  reason: 'Better internationalization support and clearer data model',
  migrationGuide: 'https://docs.example.com/migration/name-split',
  timeline: {
    announced: new Date('2024-01-15'),
    newVersionAvailable: new Date('2024-02-01'),
    deprecationStart: new Date('2024-04-01'),
    deprecationEnd: new Date('2024-07-01'),
  },
  impact: 'high',
};
 
// Notify affected consumers
async function notifyAffectedConsumers(announcement: BreakingChangeAnnouncement) {
  // 1. Email registered developers
  const affectedUsers = await getAffectedConsumers(announcement.affectedEndpoints);
  await sendEmail(affectedUsers, formatAnnouncementEmail(announcement));
  
  // 2. Post to developer blog
  await publishBlogPost(formatBlogPost(announcement));
  
  // 3. Update status page
  await updateStatusPage('planned-change', announcement);
  
  // 4. Add in-API warnings (deprecation headers)
  await scheduleDeprecationHeaders(announcement);
  
  // 5. Update documentation
  await markEndpointsDeprecated(announcement.affectedEndpoints);
}

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

// Automated Change Evaluation
 
interface ProposedChange {
  type: 'add' | 'remove' | 'modify' | 'rename';
  target: 'field' | 'endpoint' | 'parameter' | 'type';
  location: string;  // e.g., "POST /users request.body.email"
  before?: schema;
  after?: schema;
}
 
function evaluateChange(change: ProposedChange): ChangeEvaluation {
  const evaluation: ChangeEvaluation = {
    change,
    isBreaking: false,
    reason: '',
    mitigation: '',
  };
  
  // Rule 1: Removals are always breaking
  if (change.type === 'remove') {
    evaluation.isBreaking = true;
    evaluation.reason = 'Removal of existing API element';
    evaluation.mitigation = 'Deprecate first, maintain for migration period';
    return evaluation;
  }
  
  // Rule 2: Renames are breaking (they're remove + add)
  if (change.type === 'rename') {
    evaluation.isBreaking = true;
    evaluation.reason = 'Rename is effectively removal of old name';
    evaluation.mitigation = 'Add new name, deprecate old, support both temporarily';
    return evaluation;
  }
  
  // Rule 3: Type changes are breaking
  if (change.type === 'modify' && typeChanged(change.before, change.after)) {
    evaluation.isBreaking = true;
    evaluation.reason = 'Type change breaks existing serialization';
    evaluation.mitigation = 'Add new field with new type, deprecate old';
    return evaluation;
  }
  
  // Rule 4: New required fields in requests are breaking
  if (change.type === 'add' && 
      change.target === 'field' && 
      isRequestLocation(change.location) &&
      isRequired(change.after)) {
    evaluation.isBreaking = true;
    evaluation.reason = 'Required field breaks existing requests';
    evaluation.mitigation = 'Make optional with default, or version bump';
    return evaluation;
  }
  
  // Rule 5: Stricter validation is breaking
  if (change.type === 'modify' && validationStricter(change.before, change.after)) {
    evaluation.isBreaking = true;
    evaluation.reason = 'Stricter validation rejects previously valid requests';
    evaluation.mitigation = 'Apply to new version only';
    return evaluation;
  }
  
  // Non-breaking: additions to responses, relaxed validation, etc.
  evaluation.reason = 'Additive or relaxing change';
  return evaluation;
}