api-backward-compatibility

API Backward Compatibility

Core Principle

Once an API is public (has consumers you do not fully control), every change must be backward compatible unless you go through a formal deprecation process. Stripe is the gold standard: their API versions from 2011 still work. Aim for that level of stability.

---

1. The Additive-Only Changes Rule

Safe changes (backward compatible):

• Adding a new optional field to a request body.
• Adding a new field to a response body.
• Adding a new endpoint.
• Adding a new optional query parameter.
• Adding a new enum value (if consumers handle unknown values gracefully).
• Adding a new webhook event type.

Breaking changes (require versioning or migration):

• Removing or renaming a field from a response.
• Removing or renaming a field from a request.
• Changing a field's type (string to integer, etc.).
• Changing the meaning or behavior of an existing field.
• Making an optional field required.
• Changing the URL path of an existing endpoint.
• Changing error response shapes or status codes.
• Removing an enum value.
• Changing default values in ways that alter behavior.

Enforcement

Every API pull request must answer: "Can an existing consumer send the same request and get a response they can still parse?" If the answer is no, the change is breaking.

// SAFE: Adding a new optional field to the response
// Before
{ "id": "usr_123", "name": "Alice" }
// After -- existing consumers ignore the new field
{ "id": "usr_123", "name": "Alice", "avatar_url": "https://..." }

// BREAKING: Renaming a field
// Before
{ "id": "usr_123", "name": "Alice" }
// After -- existing consumers looking for "name" will break
{ "id": "usr_123", "display_name": "Alice" }

// SAFE way to rename: keep both, deprecate old
{ "id": "usr_123", "name": "Alice", "display_name": "Alice" }

---

2. Versioning Strategies

Strategy A: URL Path Versioning

GET /v1/users/123
GET /v2/users/123

• Pros: Explicit, easy to understand, easy to route.
• Cons: Encourages big-bang version bumps. Hard to maintain many versions.
• Best for: Public APIs with long-lived consumers.