How to Design APIs That Never Break Their Clients

The Incident

This isn’t a hypothetical. It’s a pattern that plays out at companies of every size - from early-stage startups to Stripe, Twilio, and GitHub. The root cause is always the same: the API was designed to be changed, not to be evolved.

There’s a difference. And this post is about that difference.

What Even Counts as a Breaking Change?

Before we talk solutions, let’s sharpen our intuition. Not every change breaks clients. But some changes that look harmless absolutely do.

// Renaming a field
{ "user_name": "anshuman" }
→
{ "username": "anshuman" }

// Removing a field entirely
{ "user_name": "anshuman", "email": "..." }
→
{ "username": "anshuman" }   // email gone!

// Changing a field's type
{ "age": "27" }   // was string
→
{ "age": 27 }     // now number

// Changing HTTP status codes
GET /users/999
was: 200 { "user": null }
now: 404  ← clients checking for 200 break

// Restructuring the response shape
{ "data": { "id": 1 } }
→
{ "result": { "user_id": 1 } }

// Adding required fields to request body
POST /orders
was: { "item_id": 1 }
now: { "item_id": 1, "warehouse": "required!" }

// Adding optional fields to response
{ "id": 1, "name": "Anshuman" }
→
{ "id": 1, "name": "Anshuman",
"avatar_url": "https://..." }  // new, optional

// Adding optional fields to request
POST /orders
{ "item_id": 1 }          // old clients still work
{ "item_id": 1, "note": "gift wrap" } // new field optional

// Adding new endpoints entirely
GET /v1/users/:id          // unchanged
POST /v1/users/:id/avatar  // brand new

// New enum values (with caveats)
{ "status": "active" | "inactive" }
→
{ "status": "active" | "inactive" | "pending" }
// ⚠️ only safe if clients use default/fallback

// Relaxing validation rules
was: name max 50 chars
now: name max 200 chars

The mental model: think of your API as a contract. Your clients write code that depends on the exact shape of your response. Every field name, every type, every status code - it’s all load-bearing. Changing any of it is demolishing a wall without checking if it’s structural.

The 4 Versioning Strategies

There are four main ways to version an API. Each is a different answer to the question: “Where does the version live?“

Strategy Deep-Dive: URL Path Versioning

This is what most teams use, and for good reason. Let’s look at what it actually means in practice.

# v1 - original
GET /api/v1/users/42
Response:
{
"user_name": "anshuman",
"email": "anshuman@example.com"
}

# v2 - new shape, runs in parallel
GET /api/v2/users/42
Response:
{
"username": "anshuman",
"contact": {
"email": "anshuman@example.com",
"phone": null
}
}

Both run simultaneously. Old clients keep hitting /v1. New clients use /v2. The URL is the contract, and the version is part of the contract.

The Stripe Approach: Header Versioning with Date Pins

Stripe is the gold standard for API design. Their versioning is subtle but brilliant:

POST https://api.stripe.com/v1/charges
Stripe-Version: 2024-06-20
Authorization: Bearer sk_live_...

There’s only one “version” in the URL (/v1/) and it’s been there forever. The actual version is passed as a date header. Every API key has a version anchor - the date of the Stripe version active when you created the key.

This means:

• You never have to upgrade unless you want to
• You opt-in to breaking changes deliberately
• Stripe can evolve aggressively without breaking anyone

The Golden Rules of API Evolution

1. Never remove a field - deprecate it first

   Mark fields with a deprecated: true flag in your OpenAPI spec. Add a Deprecation response header. Document the sunset date. Run in parallel for at least 6 months.

2. Only add, never remove or rename

   Additive changes are always safe. Old clients ignore fields they don’t understand. New clients get richer responses. This is the Robustness Principle in action: “be conservative in what you send, liberal in what you accept.”

3. Treat your API schema like a database migration

   Would you drop a column with live traffic on it? No - you’d use the Expand/Contract pattern: add the new column, migrate data, dual-write to both, then eventually remove the old one. Same logic applies to API fields.

4. Never change a field’s type

   Changing “age”: “27” to “age”: 27 seems harmless. It’s not. Clients that pass this to a typed function will throw a runtime error. If you must, add a new field: age_int, deprecate the old one.

5. Extend enums carefully

   Adding a new enum value is a “soft” breaking change. Any client with exhaustive pattern matching (TypeScript discriminated unions, Swift enums, Kotlin sealed classes) will fail at compile time or throw at runtime. Document that clients must handle unknown values.

6. Document your stability guarantees explicitly

   Tell your consumers what they can count on. Kubernetes does this with alpha / beta / stable labels. Twitter’s API has “frozen” endpoints that don’t change. Make the contract explicit so clients know what to trust.

7. Version from day one, not day one-hundred

   The cost of adding /v1/ to your routes on day one is near zero. The cost of retrofitting versioning after you have 50 production clients is enormous - and painful for everyone.

The Expand/Contract Pattern for API Evolution

This is the single most useful pattern for evolving APIs without breakage. It mirrors database migration strategy and it works at the API level too.

Phase 1 - EXPAND: add the new thing alongside the old
──────────────────────────────────────────────────────
Response:
{
"user_name": "anshuman",      ← old field, still here
"username": "anshuman",       ← new field, added
"email": "..."
}

Phase 2 - MIGRATE: move clients to the new field
──────────────────────────────────────────────────────
- Update your SDKs and docs to use "username"
- Alert power users / enterprise clients
- Track usage of "user_name" in your analytics
- Wait until "user_name" usage drops to near zero

Phase 3 - CONTRACT: remove the old thing
──────────────────────────────────────────────────────
- Once usage is negligible, remove "user_name"
- Announce the sunset date well in advance
- Log a warning for any client still sending "user_name"

Deprecation Without Drama

Deprecation is not just about deleting code - it’s a communication strategy. Here’s how to do it well.

In your OpenAPI/Swagger spec:

/users/{id}:
get:
responses:
'200':
content:
application/json:
schema:
properties:
user_name:
type: string
deprecated: true          # ← marks it in the spec
description: "Deprecated. Use `username` instead. Will be removed 2027-01-01."
username:
type: string

In your response headers:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
Link: <https://api.yourco.com/docs/migration/v2>; rel="deprecation"

In your error logs:

// Log a warning when deprecated field is accessed
if (clientUsedDeprecatedField) {
logger.warn({
event: 'deprecated_field_access',
field: 'user_name',
clientId: req.clientId,
sunset: '2027-01-01'
});
}

This gives you the data to know exactly which clients are still using the old field - so you can reach out to them proactively rather than surprising them.

Strategy Comparison

The Versioning Lifecycle Diagram

Real-World Example: Evolving a User Profile Endpoint

Let’s walk through a concrete evolution scenario end-to-end.

The starting point:

GET /api/v1/users/42
{
"user_name": "anshuman",
"full_name": "Anshuman Singh",
"email": "anshuman@example.com"
}

The desired end state (after product decides to restructure):

{
"username": "anshuman",
"profile": {
"display_name": "Anshuman Singh",
"contact": {
"email": "anshuman@example.com"
}
}
}

The wrong way: rename everything, merge to main, deploy. Wake up to PagerDuty alerts.

The right way:

Step 1 - EXPAND (Week 1): Serve both shapes simultaneously
───────────────────────────────────────────────────────────
{
"user_name": "anshuman",          // old, still here
"username": "anshuman",           // new, added
"full_name": "Anshuman Singh",    // old
"profile": {
"display_name": "Anshuman Singh"
},
"email": "anshuman@example.com",  // old
"_meta": {
"deprecated_fields": ["user_name", "full_name", "email"],
"sunset_date": "2027-03-01"
}
}

Step 2 - COMMUNICATE (Week 2): Notify clients
───────────────────────────────────────────────────────────
- Update changelog
- Send email to API key holders
- Add Deprecation + Sunset headers
- Track usage of old fields in your metrics

Step 3 - CONTRACT (Month 6+): Remove when usage is <1%
───────────────────────────────────────────────────────────
Remove old fields. Celebrate.

Frequently Asked Questions

Interview Questions

These come up regularly in system design rounds, especially at FAANG-tier and late-stage startups.

The Mental Model to Take Away

Priya’s 2 AM incident could have been prevented with one shift in thinking: treat your API as a published contract, not a private implementation detail.

Your clients - whether they’re a mobile app, a third-party integration, or another team’s microservice - write real code against your API. Every field name is a variable name in their codebase. Every status code is a branch in their error handler.

When you evolve an API:

• Add, don’t replace. New fields can coexist with old ones.
• Deprecate loudly, remove quietly. Give clients time, data, and a migration guide.
• Version from day one. /v1/ costs nothing to add on day one and everything to retrofit later.
• Measure before you remove. Use your own logs to know when it’s safe to cut the old field.
• Return 410, not 404. Signal intent, not absence.

The best API is one that clients barely notice evolving - because it does so gracefully, predictably, and always with them in mind.