System Design (LLD)API Versioning

API Versioning

LevelIntermediate

Duration60 mins

TopicAPI Versioning

3 / 5

Breaking vs Non-Breaking Changes

The Classification That Matters Most

Versioning only has meaning when you can distinguish between changes that require a new version and changes that don't. This distinction—between breaking and non-breaking changes—is the most critical skill in API lifecycle management.

Breaking changes violate the existing contract and may cause consumer integrations to fail. They must be isolated in new versions.

Non-breaking changes extend or improve the API without violating existing contracts. They can be deployed within the current version safely.

The challenge is that this classification isn't always obvious. What seems like a minor tweak can be breaking. What seems like a major addition might be perfectly safe. This page provides the comprehensive framework you need to make these distinctions confidently.

The Asymmetry of Breaking Changes

Here's the crucial asymmetry: you can never un-break something. Once a breaking change reaches consumers in a released version, the damage is done. Therefore, the default should be to assume a change is breaking until you've thoroughly analyzed why it isn't. Err on the side of caution.

Understanding API Contracts

Before classifying changes, we need to understand what constitutes the 'contract' that breaking changes violate.

The Explicit Contract:

This is what you've formally documented and promised:

Request structure (paths, parameters, headers, body format)
Response structure (fields, types, status codes)
Error formats and codes
Behavioral guarantees (idempotency, ordering)
Authentication and authorization mechanisms

The Implicit Contract:

This is more dangerous—behaviors that aren't documented but that consumers depend on:

Field ordering in responses (some parsers are order-sensitive)
Null vs. absent field handling
Default values when fields are omitted
Timing characteristics
Case sensitivity in strings
Precision of numerical values

Hyrum's Law:

Google engineer Hyrum Wright articulated a principle that every API designer should internalize:

"With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody."

This means consumers will depend on any consistent behavior, documented or not. A timestamp format, the order of array elements, the presence of whitespace—if it's consistent, someone will depend on it.

Contract Documentation Strategy

The best defense against implicit contracts becoming breaking changes is to explicitly document what is NOT guaranteed. For example: 'Field ordering in responses is not guaranteed and may change without notice.' This lets you freely modify unguaranteed aspects without violating explicit promises.

Contract Types and Risk Levels
Contract Type	Example	Modification Risk
Explicit (documented)	Response includes `user.id` field of type integer	Breaking if removed/changed
Implicit (behavioral)	`user.tags` array returns in creation order	Potentially breaking if changed
Incidental (random)	Request takes ~200ms to complete	Generally safe to change
Explicitly disclaimed	'Field ordering may change'	Safe to change

Definitive Breaking Changes

Some changes are unambiguously breaking—they will cause client integrations to fail immediately. Any of the following changes MUST go into a new major version:

Request-Side Breaking Changes

•Removing an endpoint — Any endpoint that previously worked now returns 404
•Changing HTTP method — Endpoint changes from POST to PUT (clients will get 405)
•Adding required parameters — Existing requests without the new parameter will fail
•Removing optional parameters — Clients still sending them may get errors
•Changing parameter types — String to integer, array to object, etc.
•Renaming parameters — user_id becoming userId breaks existing requests
•Changing URL structure — /users/{id}/posts becoming /users/{id}/articles
•Tightening validation — Rejecting previously accepted values
•Changing authentication — New auth requirements, different token formats

Response-Side Breaking Changes

•Removing response fields — Clients reading user.email break when it's gone
•Changing field types — id from integer to UUID string
•Renaming response fields — created_at to createdAt
•Restructuring responses — Moving user.email to user.contact.email
•Changing status codes — 200 to 201, or 400 to 422
•Changing error formats — Different error object structure
•Changing null handling — Previously absent field now returns null (or vice versa)
•Changing array to single object — Or vice versa
•Changing enum values — Removing possible values, renaming them

breaking-change-examples
JSON
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
// ❌ BREAKING: Field Removal
// Before:
{
  "user": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com"  // Removed in new version
  }
}
 
// After (BREAKING - clients expecting 'email' will break):
{
  "user": {
    "id": 123,
    "name": "John Doe"
  }
}
 
// ❌ BREAKING: Field Type Change
// Before:
{
  "order": {
    "id": 12345,        // Integer
    "total": 99.99
  }
}
 
// After (BREAKING - clients parsing integer will break):
{
  "order": {
    "id": "ord_a1b2c3",  // String (UUID)
    "total": 99.99
  }
}
 
// ❌ BREAKING: Structure Change
// Before:
{
  "user": {
    "address": "123 Main St, City, 12345"  // Single string
  }
}
 
// After (BREAKING - clients expecting string will break):
{
  "user": {
    "address": {           // Now an object
      "street": "123 Main St",
      "city": "City",
      "zip": "12345"
    }
  }
}

No Exceptions

These changes are breaking regardless of how you communicate them. Even with advance warning, extensive documentation, and migration guides—the technical reality remains: existing client code will fail. Always isolate these changes in a new major version.

Definitive Non-Breaking Changes

Some changes are unambiguously safe and can be deployed within the current version without risk to existing consumers:

Safe Non-Breaking Changes

•Adding new endpoints — New paths don't affect existing integration
•Adding optional request parameters — Existing requests without them continue working
•Adding new response fields — Clients ignore fields they don't recognize
•Adding new enum values — Existing values remain valid (with caveats—see below)
•Adding new HTTP methods — Supporting PATCH alongside PUT doesn't break PUT
•Loosening validation — Accepting broader input than before
•Performance improvements — Faster responses don't break clients
•Adding optional headers — New headers don't affect requests without them
•Internal implementation changes — Changed algorithms, databases, etc. (same external behavior)

non-breaking-examples
JSON
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
// ✅ NON-BREAKING: Adding new fields
// Before:
{
  "user": {
    "id": 123,
    "name": "John Doe"
  }
}
 
// After (safe - clients can ignore new fields):
{
  "user": {
    "id": 123,
    "name": "John Doe",
    "avatar_url": "https://cdn.example.com/123.jpg",  // New field
    "created_at": "2024-01-15T10:30:00Z"              // New field
  }
}
 
// ✅ NON-BREAKING: Adding optional parameters
// Before:
// POST /search
// { "query": "shoes" }
 
// After (safe - existing requests still work):
// POST /search  
// { "query": "shoes", "filters": { "size": 10 } }  // Optional new param
// { "query": "shoes" }  // Still works without filters
 
// ✅ NON-BREAKING: Adding new endpoints
// Before: /users, /products
 
// After (safe - new endpoint doesn't affect existing ones):
// /users, /products, /reviews  // New endpoint added
 
// ✅ NON-BREAKING: Loosening validation
// Before: username must be 5-20 characters
 
// After (safe - existing valid inputs still valid):
// username must be 3-50 characters  // Accepts more inputs

The Additive Principle

The general principle: adding is safe, removing is breaking, changing is breaking. If you only add new capabilities without modifying existing ones, you're generally safe. This is why forward-thinking API design leaves room for extension.

The Ambiguous Gray Zone

Between obvious breaking and obvious non-breaking changes lies a gray zone—changes that might break some consumers depending on implementation details. These require careful analysis:

Adding New Enum Values:

Seems safe, but can break clients that use exhaustive switch statements:

// Client code with exhaustive matching
switch (order.status) {
    case 'pending': return handlePending();
    case 'completed': return handleCompleted();
    case 'cancelled': return handleCancelled();
    default: throw new Error('Unknown status!');  // BREAKS with new status
}

If you add a new enum value like 'refunded', clients with exhaustive handling will fail. Well-designed clients should handle unknown values gracefully, but many don't.

Recommendation: Document that enums may expand. Add new values in minor versions but announce them clearly.

Changing Default Values:

If an optional parameter's default changes, clients relying on the default behavior experience different results:

// Before: GET /items?limit defaults to 10
// After: GET /items?limit defaults to 20

Clients expecting 10 items now get 20. Depending on their pagination logic, this could cause issues.

Recommendation: Treat default value changes as potentially breaking. Consider whether any consumer could reasonably depend on the current default.

Changing Null Semantics:

The difference between 'field absent' and 'field is null' matters to some implementations:

// Before: field absent if no value
{ "user": { "name": "John" } }  // email absent

// After: field present but null
{ "user": { "name": "John", "email": null } }  // email is null

Some parsing frameworks treat these differently.

Recommendation: Be consistent and document your null semantics. Changes here may be breaking for some consumers.

Gray Zone Changes: Analysis and Recommendations
Change	Breaking For	Safe For	Recommendation
Adding enum values	Exhaustive matchers	Tolerant parsers	Document enum expansion; warn before adding
Changing defaults	Clients relying on defaults	Clients specifying explicitly	Treat as potentially breaking
Null vs absent	Strict null checkers	Lenient parsers	Be consistent; document policy
Changing field ordering	Order-dependent parsers	Most JSON parsers	Disclaim ordering; test before changing
Changing string formats	Strict validators	Lenient parsers	Consider breaking; prefer new fields
Changing precision	High-precision use cases	Display-only use cases	Document precision guarantees

When in Doubt

If a change falls into the gray zone and you're unsure whether it will break consumers, treat it as breaking. The cost of an unnecessary version bump is far lower than the cost of breaking production integrations.

Behavioral vs Structural Changes

A subtle but important distinction exists between changes to the API's structure (what it looks like) and its behavior (what it does). Both can be breaking.

Structural Changes:

These affect the 'shape' of requests and responses:

Field names and types
Endpoint paths
Parameter requirements
Response envelope structure

Structural changes are usually obvious—the API literally looks different.

Behavioral Changes:

These change what the API does without changing its appearance:

Different business logic for the same inputs
Changed side effects (notifications, logging)
Modified error conditions
Changed ordering of results
Different timing characteristics

Behavioral changes are insidious because the API appears unchanged:

// Request/response structure identical before and after
POST /orders
{ "product_id": 123, "quantity": 2 }

// But behavior changed:
// Before: Allowed any quantity
// After: Rejects quantity > 10 with validation error

The structural contract is preserved, but consumers expecting to order 50 items now receive errors.

Breaking Behavioral Changes

•Adding new validation rules that reject previously valid input
•Changing what triggers an error condition
•Removing side effects consumers depend on (emails, webhooks)
•Changing result ordering when order was implicitly guaranteed
•Making operations fail that previously succeeded

Non-Breaking Behavioral Changes

•Performance improvements with same results
•Internal refactoring with identical outputs
•Adding optional side effects (opt-in notifications)
•Bug fixes that correct clearly incorrect behavior
•Security hardening that doesn't change success cases

The Bug Fix Dilemma

Bug fixes present a philosophical challenge: if the API was 'wrong' according to documentation but consumers built on the buggy behavior, is fixing the bug breaking? Technically yes, practically it depends. For minor discrepancies, document the fix and monitor. For major behavior changes, consider a new version or a feature flag to opt into correct behavior.

Semantic Versioning for APIs

Semantic Versioning (SemVer) provides a formal framework for communicating change types through version numbers:

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └─ Bug fixes, no API changes
  │     └─ New features, backward compatible  
  └─ Breaking changes

Applying SemVer to APIs:

MAJOR (X.y.z): Increment when making breaking changes

Removing endpoints or fields
Changing types or required parameters
Restructuring responses
Changing authentication mechanisms

MINOR (x.Y.z): Increment when adding backward-compatible functionality

New endpoints
New optional parameters
New response fields
New enum values

PATCH (x.y.Z): Increment for backward-compatible fixes

Bug fixes that don't change API behavior
Documentation corrections
Performance improvements

Practical API Versioning:

Most APIs don't expose full SemVer to consumers. Instead:

Public version is major only: /v1/, /v2/
Minor/patch changes deploy within the major version
Internal versioning may use full SemVer for tracking

This simplifies the consumer experience while maintaining semantic precision internally.

semver-api-example
Markdown
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
# API Changelog (Internal SemVer, Public Major Only)
 
## v2 (Public API Version)
 
### 2.3.0 (2024-06-15) - Minor
- Added: `user.preferences` field in GET /users/{id}
- Added: Optional `timezone` parameter in POST /events
- Added: GET /analytics/overview endpoint
 
### 2.2.1 (2024-05-20) - Patch
- Fixed: Improved rate limiting accuracy
- Fixed: Documentation typo in error codes
 
### 2.2.0 (2024-04-10) - Minor
- Added: `cursor` pagination option alongside offset
- Added: `archived` status to order enum
 
## v1 (Public API Version) - DEPRECATED
 
### 1.15.0 (2024-03-01) - Minor (final v1 release)
- Added: Deprecation warnings in response headers
- Note: v1 sunset date: 2024-09-01
 
---
 
# Breaking Changes Log (Major Version Decisions)
 
## v1 → v2 Breaking Changes
- REMOVED: `user.legacy_id` field
- CHANGED: `order.id` from integer to UUID string  
- CHANGED: Error response format (code → error_code)
- REMOVED: Basic Authentication support
- CHANGED: Rate limit from 100/min to 60/min

Changelog as Contract

Maintain a meticulous changelog that classifies every change by type. This serves as both documentation for consumers and a forcing function for your team to think carefully about change classification. If you can't clearly categorize a change, you haven't thought it through.

Designing for Forward Compatibility

The best way to handle breaking changes is to need fewer of them. Good API design anticipates evolution and leaves room for extension.

Response Envelopes:

Wrap responses in extensible envelopes:

{
  "data": { ... actual data ... },
  "meta": { ... pagination, timestamps, etc. ... },
  "links": { ... HATEOAS links ... }
}

This structure lets you add new top-level concerns (error details, rate limit info, deprecation notices) without touching the data payload.

Prefer Objects Over Primitives:

// Problematic:
{ "avatar": "https://cdn.example.com/123.jpg" }

// Better:
{ "avatar": { "url": "https://cdn.example.com/123.jpg" } }

The object form allows adding width, height, thumbnail_url later without restructuring.

Use Explicit Null and Omission Policies:

Document whether absent means 'not applicable', 'unknown', 'null', or 'not requested'. This lets you add new optional fields without ambiguity.

Design Extensible Status/Type Enums:

// In documentation:
// "status" can be: "active", "inactive", "pending"
// Note: status values may be added in future versions;
// clients should handle unknown statuses gracefully.

Version Your Content Types Early:

Even if not using content negotiation for versioning, include version hints:

Content-Type: application/json; api-version=2

Forward Compatibility Checklist

•Response envelopes — Wrap data in extensible structures
•Object fields — Use objects instead of primitives where extension is likely
•Documented extensibility — State explicitly that new fields may appear
•Enum expansion — Document that enum values may grow
•Null semantics — Define and document null/absent distinction
•Flexible parsing — Advise clients to ignore unknown fields
•Stable field names — Use names that won't need changing
•Avoid overloading — Don't pile multiple meanings onto single fields

Summary: Classifying Changes

Understanding breaking vs non-breaking changes is central to API versioning. Let's consolidate the key insights:

Key Takeaways

•Breaking changes violate the API contract — Removing, renaming, restructuring, or retyping elements breaks consumers.
•Non-breaking changes extend without modifying — Adding new optional elements is generally safe.
•Gray zone changes require careful analysis — Defaults, null semantics, and enum additions need case-by-case evaluation.
•Both structure and behavior can break — Identical API structure can hide behavioral changes that break consumers.
•Hyrum's Law is real — Any observable behavior becomes part of the implicit contract; plan for this.
•Design for extension from the start — Envelopes, objects, and documentation reduce future breaking changes.
•When uncertain, treat as breaking — The cost of false positives is much lower than breaking integrations.

What's Next:

Even with perfect classification, breaking changes will eventually be necessary. The final page of this module covers deprecation handling—how to communicate, transition, and eventually retire old API versions while minimizing disruption to your consumers.

Page Complete

You now have a comprehensive framework for classifying API changes. This skill is essential for maintaining consumer trust while evolving your API over time. Next, we'll cover the equally important topic of gracefully deprecating and retiring old versions.

3 / 5

Loading learning content...

System Design (LLD)API Versioning

API Versioning

LevelIntermediate

Duration60 mins

TopicAPI Versioning

3 / 5

Breaking vs Non-Breaking Changes

The Classification That Matters Most

Breaking changes violate the existing contract and may cause consumer integrations to fail. They must be isolated in new versions.

Non-breaking changes extend or improve the API without violating existing contracts. They can be deployed within the current version safely.

The Asymmetry of Breaking Changes

Understanding API Contracts

Before classifying changes, we need to understand what constitutes the 'contract' that breaking changes violate.

The Explicit Contract:

This is what you've formally documented and promised:

Request structure (paths, parameters, headers, body format)
Response structure (fields, types, status codes)
Error formats and codes
Behavioral guarantees (idempotency, ordering)
Authentication and authorization mechanisms

The Implicit Contract:

This is more dangerous—behaviors that aren't documented but that consumers depend on:

Field ordering in responses (some parsers are order-sensitive)
Null vs. absent field handling
Default values when fields are omitted
Timing characteristics
Case sensitivity in strings
Precision of numerical values

Hyrum's Law:

Google engineer Hyrum Wright articulated a principle that every API designer should internalize:

"With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody."

Contract Documentation Strategy

Contract Types and Risk Levels
Contract Type	Example	Modification Risk
Explicit (documented)	Response includes `user.id` field of type integer	Breaking if removed/changed
Implicit (behavioral)	`user.tags` array returns in creation order	Potentially breaking if changed
Incidental (random)	Request takes ~200ms to complete	Generally safe to change
Explicitly disclaimed	'Field ordering may change'	Safe to change

Definitive Breaking Changes

Some changes are unambiguously breaking—they will cause client integrations to fail immediately. Any of the following changes MUST go into a new major version:

Request-Side Breaking Changes

•Removing an endpoint — Any endpoint that previously worked now returns 404
•Changing HTTP method — Endpoint changes from POST to PUT (clients will get 405)
•Adding required parameters — Existing requests without the new parameter will fail
•Removing optional parameters — Clients still sending them may get errors
•Changing parameter types — String to integer, array to object, etc.
•Renaming parameters — user_id becoming userId breaks existing requests
•Changing URL structure — /users/{id}/posts becoming /users/{id}/articles
•Tightening validation — Rejecting previously accepted values
•Changing authentication — New auth requirements, different token formats

Response-Side Breaking Changes

•Removing response fields — Clients reading user.email break when it's gone
•Changing field types — id from integer to UUID string
•Renaming response fields — created_at to createdAt
•Restructuring responses — Moving user.email to user.contact.email
•Changing status codes — 200 to 201, or 400 to 422
•Changing error formats — Different error object structure
•Changing null handling — Previously absent field now returns null (or vice versa)
•Changing array to single object — Or vice versa
•Changing enum values — Removing possible values, renaming them

breaking-change-examples
JSON
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
// ❌ BREAKING: Field Removal
// Before:
{
  "user": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com"  // Removed in new version
  }
}
 
// After (BREAKING - clients expecting 'email' will break):
{
  "user": {
    "id": 123,
    "name": "John Doe"
  }
}
 
// ❌ BREAKING: Field Type Change
// Before:
{
  "order": {
    "id": 12345,        // Integer
    "total": 99.99
  }
}
 
// After (BREAKING - clients parsing integer will break):
{
  "order": {
    "id": "ord_a1b2c3",  // String (UUID)
    "total": 99.99
  }
}
 
// ❌ BREAKING: Structure Change
// Before:
{
  "user": {
    "address": "123 Main St, City, 12345"  // Single string
  }
}
 
// After (BREAKING - clients expecting string will break):
{
  "user": {
    "address": {           // Now an object
      "street": "123 Main St",
      "city": "City",
      "zip": "12345"
    }
  }
}

No Exceptions

Definitive Non-Breaking Changes

Some changes are unambiguously safe and can be deployed within the current version without risk to existing consumers:

Safe Non-Breaking Changes

•Adding new endpoints — New paths don't affect existing integration
•Adding optional request parameters — Existing requests without them continue working
•Adding new response fields — Clients ignore fields they don't recognize
•Adding new enum values — Existing values remain valid (with caveats—see below)
•Adding new HTTP methods — Supporting PATCH alongside PUT doesn't break PUT
•Loosening validation — Accepting broader input than before
•Performance improvements — Faster responses don't break clients
•Adding optional headers — New headers don't affect requests without them
•Internal implementation changes — Changed algorithms, databases, etc. (same external behavior)

non-breaking-examples
JSON
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
// ✅ NON-BREAKING: Adding new fields
// Before:
{
  "user": {
    "id": 123,
    "name": "John Doe"
  }
}
 
// After (safe - clients can ignore new fields):
{
  "user": {
    "id": 123,
    "name": "John Doe",
    "avatar_url": "https://cdn.example.com/123.jpg",  // New field
    "created_at": "2024-01-15T10:30:00Z"              // New field
  }
}
 
// ✅ NON-BREAKING: Adding optional parameters
// Before:
// POST /search
// { "query": "shoes" }
 
// After (safe - existing requests still work):
// POST /search  
// { "query": "shoes", "filters": { "size": 10 } }  // Optional new param
// { "query": "shoes" }  // Still works without filters
 
// ✅ NON-BREAKING: Adding new endpoints
// Before: /users, /products
 
// After (safe - new endpoint doesn't affect existing ones):
// /users, /products, /reviews  // New endpoint added
 
// ✅ NON-BREAKING: Loosening validation
// Before: username must be 5-20 characters
 
// After (safe - existing valid inputs still valid):
// username must be 3-50 characters  // Accepts more inputs

The Additive Principle

The Ambiguous Gray Zone

Between obvious breaking and obvious non-breaking changes lies a gray zone—changes that might break some consumers depending on implementation details. These require careful analysis:

Adding New Enum Values:

Seems safe, but can break clients that use exhaustive switch statements:

// Client code with exhaustive matching
switch (order.status) {
    case 'pending': return handlePending();
    case 'completed': return handleCompleted();
    case 'cancelled': return handleCancelled();
    default: throw new Error('Unknown status!');  // BREAKS with new status
}

If you add a new enum value like 'refunded', clients with exhaustive handling will fail. Well-designed clients should handle unknown values gracefully, but many don't.

Recommendation: Document that enums may expand. Add new values in minor versions but announce them clearly.

Changing Default Values:

If an optional parameter's default changes, clients relying on the default behavior experience different results:

// Before: GET /items?limit defaults to 10
// After: GET /items?limit defaults to 20

Clients expecting 10 items now get 20. Depending on their pagination logic, this could cause issues.

Recommendation: Treat default value changes as potentially breaking. Consider whether any consumer could reasonably depend on the current default.

Changing Null Semantics:

The difference between 'field absent' and 'field is null' matters to some implementations:

// Before: field absent if no value
{ "user": { "name": "John" } }  // email absent

// After: field present but null
{ "user": { "name": "John", "email": null } }  // email is null

Some parsing frameworks treat these differently.

Recommendation: Be consistent and document your null semantics. Changes here may be breaking for some consumers.

Gray Zone Changes: Analysis and Recommendations
Change	Breaking For	Safe For	Recommendation
Adding enum values	Exhaustive matchers	Tolerant parsers	Document enum expansion; warn before adding
Changing defaults	Clients relying on defaults	Clients specifying explicitly	Treat as potentially breaking
Null vs absent	Strict null checkers	Lenient parsers	Be consistent; document policy
Changing field ordering	Order-dependent parsers	Most JSON parsers	Disclaim ordering; test before changing
Changing string formats	Strict validators	Lenient parsers	Consider breaking; prefer new fields
Changing precision	High-precision use cases	Display-only use cases	Document precision guarantees

When in Doubt

Behavioral vs Structural Changes

A subtle but important distinction exists between changes to the API's structure (what it looks like) and its behavior (what it does). Both can be breaking.

Structural Changes:

These affect the 'shape' of requests and responses:

Field names and types
Endpoint paths
Parameter requirements
Response envelope structure

Structural changes are usually obvious—the API literally looks different.

Behavioral Changes:

These change what the API does without changing its appearance:

Different business logic for the same inputs
Changed side effects (notifications, logging)
Modified error conditions
Changed ordering of results
Different timing characteristics

Behavioral changes are insidious because the API appears unchanged:

// Request/response structure identical before and after
POST /orders
{ "product_id": 123, "quantity": 2 }

// But behavior changed:
// Before: Allowed any quantity
// After: Rejects quantity > 10 with validation error

The structural contract is preserved, but consumers expecting to order 50 items now receive errors.

Breaking Behavioral Changes

•Adding new validation rules that reject previously valid input
•Changing what triggers an error condition
•Removing side effects consumers depend on (emails, webhooks)
•Changing result ordering when order was implicitly guaranteed
•Making operations fail that previously succeeded

Non-Breaking Behavioral Changes

•Performance improvements with same results
•Internal refactoring with identical outputs
•Adding optional side effects (opt-in notifications)
•Bug fixes that correct clearly incorrect behavior
•Security hardening that doesn't change success cases

The Bug Fix Dilemma

Semantic Versioning for APIs

Semantic Versioning (SemVer) provides a formal framework for communicating change types through version numbers:

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └─ Bug fixes, no API changes
  │     └─ New features, backward compatible  
  └─ Breaking changes

Applying SemVer to APIs:

MAJOR (X.y.z): Increment when making breaking changes

Removing endpoints or fields
Changing types or required parameters
Restructuring responses
Changing authentication mechanisms

MINOR (x.Y.z): Increment when adding backward-compatible functionality

New endpoints
New optional parameters
New response fields
New enum values

PATCH (x.y.Z): Increment for backward-compatible fixes

Bug fixes that don't change API behavior
Documentation corrections
Performance improvements

Practical API Versioning:

Most APIs don't expose full SemVer to consumers. Instead:

Public version is major only: /v1/, /v2/
Minor/patch changes deploy within the major version
Internal versioning may use full SemVer for tracking

This simplifies the consumer experience while maintaining semantic precision internally.

semver-api-example
Markdown
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
# API Changelog (Internal SemVer, Public Major Only)
 
## v2 (Public API Version)
 
### 2.3.0 (2024-06-15) - Minor
- Added: `user.preferences` field in GET /users/{id}
- Added: Optional `timezone` parameter in POST /events
- Added: GET /analytics/overview endpoint
 
### 2.2.1 (2024-05-20) - Patch
- Fixed: Improved rate limiting accuracy
- Fixed: Documentation typo in error codes
 
### 2.2.0 (2024-04-10) - Minor
- Added: `cursor` pagination option alongside offset
- Added: `archived` status to order enum
 
## v1 (Public API Version) - DEPRECATED
 
### 1.15.0 (2024-03-01) - Minor (final v1 release)
- Added: Deprecation warnings in response headers
- Note: v1 sunset date: 2024-09-01
 
---
 
# Breaking Changes Log (Major Version Decisions)
 
## v1 → v2 Breaking Changes
- REMOVED: `user.legacy_id` field
- CHANGED: `order.id` from integer to UUID string  
- CHANGED: Error response format (code → error_code)
- REMOVED: Basic Authentication support
- CHANGED: Rate limit from 100/min to 60/min

Changelog as Contract

Designing for Forward Compatibility

The best way to handle breaking changes is to need fewer of them. Good API design anticipates evolution and leaves room for extension.

Response Envelopes:

Wrap responses in extensible envelopes:

{
  "data": { ... actual data ... },
  "meta": { ... pagination, timestamps, etc. ... },
  "links": { ... HATEOAS links ... }
}

This structure lets you add new top-level concerns (error details, rate limit info, deprecation notices) without touching the data payload.

Prefer Objects Over Primitives:

// Problematic:
{ "avatar": "https://cdn.example.com/123.jpg" }

// Better:
{ "avatar": { "url": "https://cdn.example.com/123.jpg" } }

The object form allows adding width, height, thumbnail_url later without restructuring.

Use Explicit Null and Omission Policies:

Document whether absent means 'not applicable', 'unknown', 'null', or 'not requested'. This lets you add new optional fields without ambiguity.

Design Extensible Status/Type Enums:

// In documentation:
// "status" can be: "active", "inactive", "pending"
// Note: status values may be added in future versions;
// clients should handle unknown statuses gracefully.

Version Your Content Types Early:

Even if not using content negotiation for versioning, include version hints:

Content-Type: application/json; api-version=2

Forward Compatibility Checklist

•Response envelopes — Wrap data in extensible structures
•Object fields — Use objects instead of primitives where extension is likely
•Documented extensibility — State explicitly that new fields may appear
•Enum expansion — Document that enum values may grow
•Null semantics — Define and document null/absent distinction
•Flexible parsing — Advise clients to ignore unknown fields
•Stable field names — Use names that won't need changing
•Avoid overloading — Don't pile multiple meanings onto single fields

Summary: Classifying Changes

Understanding breaking vs non-breaking changes is central to API versioning. Let's consolidate the key insights:

Key Takeaways

•Breaking changes violate the API contract — Removing, renaming, restructuring, or retyping elements breaks consumers.
•Non-breaking changes extend without modifying — Adding new optional elements is generally safe.
•Gray zone changes require careful analysis — Defaults, null semantics, and enum additions need case-by-case evaluation.
•Both structure and behavior can break — Identical API structure can hide behavioral changes that break consumers.
•Hyrum's Law is real — Any observable behavior becomes part of the implicit contract; plan for this.
•Design for extension from the start — Envelopes, objects, and documentation reduce future breaking changes.
•When uncertain, treat as breaking — The cost of false positives is much lower than breaking integrations.

What's Next:

Page Complete

3 / 5