API Versioning & Backward Compatibility

Three Approaches

✅ Safe (Backward Compatible)

• Adding new fields to responses (clients ignore unknown fields)
• Adding new endpoints (doesn't affect existing routes)
• Adding optional parameters (existing requests still work without them)
• Adding new enum values (if clients handle unknown gracefully)
• Widening a type (int32 → int64, if wire format allows)

❌ Dangerous (Breaking)

• Removing fields from responses — clients parsing them will crash
• Renaming fields — same as removing + adding
• Changing field types — "id": 42 → "id": "uuid-abc"
• Removing endpoints — 404 for active clients
• Making optional params required — existing requests become invalid
• Changing error formats — client error handling breaks

The Best Version Is No Version

If you design carefully from the start, you can often avoid versioning entirely:

• Additive-only changes: Only add fields, never remove or rename
• Optional fields with defaults: New params default to previous behavior
• Feature flags: New capabilities gated behind opt-in headers
• Tolerant readers: Document that clients MUST ignore unknown fields
• Expand/contract pattern: Add new field → migrate clients → remove old field (over months)

Pact: Don't Break Your Consumers

Consumer-driven contracts flip the testing model: instead of the API provider defining tests, each consumer defines what they expect from the API:

// Consumer (mobile app) defines its contract:
{
  "description": "get user profile",
  "request": { "method": "GET", "path": "/users/42" },
  "response": {
    "status": 200,
    "body": {
      "id": 42,       // I need this
      "name": "any",  // I need this
      "email": "any"  // I need this
    }
  }
}
// Provider runs ALL consumer contracts on every deploy
// If any break → deploy is blocked

Tools like Pact collect contracts from all consumers and verify them against the provider on every CI run. You know before deploying if a change will break any client.