Evolving APIs Without Breaking Clients: A Practical Guide for Software

Why API changes fail in production and how experienced teams avoid it.

Read first article from series is here.

Introduction: APIs don’t belong to you anymore

The moment you publish an API, it stops being just your code.

It becomes:

Someone else’s dependency
Someone else’s release risk
Someone else’s production problem

Most API failures don’t come from load or latency.
They come from unexpected change.

If backward compatibility is hard in general, APIs make it harder—because your consumers are often invisible to you.

The uncomfortable truth about API consumers

You rarely know:

Who is using your API
How often they call it
What assumptions they made
How quickly they can upgrade

Even inside the same company:

Teams move on
Ownership changes
Documentation becomes outdated

Designing APIs means designing for uncertainty.

What an API contract really is

An API contract is not just:

Endpoint URL
HTTP method
Request and response fields

It also includes:

Field meanings
Validation rules
Default values
Error behavior
Ordering and timing

Breaking any of these can break clients—even if the JSON still “looks valid”.

Example 1: The hidden breaking change

Original response:

{
  "total": 5
}

Later change:

{
  "total": "5"
}

Everything still parses.

But:

A strongly typed client fails
Calculations behave incorrectly
Bugs appear far from the API

Lesson:
Data type changes are breaking changes—even if they seem harmless.

Additive changes: the safest way forward

The safest API evolution strategy is addition.

You can safely:

Add optional fields
Add new endpoints
Add new error codes

Clients that don’t know about them simply ignore them.

Example 2: Adding instead of modifying

Instead of changing:

{
  "amount": 1000
}

Add:

{
  "amount": 1000,
  "pricing": {
    "value": 1000,
    "currency": "INR"
  }
}

Old clients keep working.
New clients get richer data.

This is boring design.
And boring is good.

When behavior changes, version the API

If the meaning of a response changes, versioning is not optional.

Example 3: Business rule change

Originally:

Order is created even if stock is low

Later:

Order fails if stock is insufficient

Same endpoint. Same request. Different outcome.

This is a breaking change—even if the response schema is unchanged.

Correct approach:

/api/v1/orders → old behavior
/api/v2/orders → new rules

Versioning is not about structure.
It’s about behavior.

Common API anti-patterns (avoid these)

Anti-pattern 1: Overloading fields

Using one field to represent multiple concepts.

{
  "status": "FAILED"
}

Does it mean:

Validation failed?
Payment failed?
System failed?

Clients guess.
Guessing leads to bugs.

Anti-pattern 2: Making optional fields mandatory

Today:

{
  "email": "user@test.com"
}

Tomorrow:

{
  "email": "user@test.com",
  "phone": "9999999999"
}

If phone becomes required:

Old clients fail validation
Deployments break unexpectedly

Rule:
Once optional, always optional—at least in the same version.

Anti-pattern 3: Silent validation tightening

Validation changes break more clients than schema changes.

Example:

Previously allowed empty string
Now rejects it

Same field. Same API. Different outcome.

This breaks clients silently.

Be liberal in what you accept

APIs should be forgiving at the edges.

Accept:

Missing optional fields
Extra fields you don’t understand
Slightly older formats

Reject only when:

Data is invalid
Security is at risk
Business rules truly require it

Strict input + no versioning = production pain.

Error handling is part of the contract

Changing error behavior is a breaking change.

Example 4: Error response change

Old:

{
  "error": "INVALID_REQUEST"
}

New:

{
  "errors": [
    { "code": "INVALID_REQUEST" }
  ]
}

Cleaner? Yes.
Backward compatible? No.

Clients parse errors too.

How experienced teams evolve APIs safely

They do three things consistently:

Design APIs as public contracts
Assume clients upgrade slowly
Measure usage before removing anything

They treat APIs like products—not internal functions.

A simple checklist before changing an API

Before you change an API, ask:

Will old clients still work?
Are we changing behavior or just adding data?
Can this be done additively?
Do we need a new version?
How long will we support the old one?

If the answer is unclear, don’t change it yet.

Final thought: APIs fail at the boundaries

Most systems don’t fail at the core logic.

They fail at the boundaries—where assumptions meet reality.

APIs are those boundaries.

Design them carefully, evolve them slowly, and never forget:
Once an API is used, it no longer belongs only to you.

More such articles:

https://medium.com/techwasti

https://www.youtube.com/@maheshwarligade

https://techwasti.com/series/spring-boot-tutorials

https://techwasti.com/series/go-language

Evolving APIs Without Breaking Clients.

Comments

Backward Compatibility

Database Changes in Live Systems.

More from this blog

Adopting an MCP-First API Design for the Agentic Era | Beyond REST.

Article 6: Mastering Kestra's Plugin Ecosystem.

Article 5: Advanced Workflow Patterns in Kestra.

Article 4: Building Your First ETL Pipeline with Kestra.

Article 3: Understanding Kestra's Architecture: Flows, Tasks, and Namespaces

Introduction: APIs don’t belong to you anymore

The uncomfortable truth about API consumers

What an API contract really is

Example 1: The hidden breaking change

Additive changes: the safest way forward

Example 2: Adding instead of modifying

When behavior changes, version the API

Example 3: Business rule change

Common API anti-patterns (avoid these)

Anti-pattern 1: Overloading fields

Anti-pattern 2: Making optional fields mandatory

Anti-pattern 3: Silent validation tightening

Be liberal in what you accept

Error handling is part of the contract

Example 4: Error response change

How experienced teams evolve APIs safely

A simple checklist before changing an API

Final thought: APIs fail at the boundaries

Command Palette

Comments

Backward Compatibility

Database Changes in Live Systems.

More from this blog

Introduction: APIs don’t belong to you anymore

The uncomfortable truth about API consumers

What an API contract really is

Example 1: The hidden breaking change

Additive changes: the safest way forward

Example 2: Adding instead of modifying

When behavior changes, version the API

Example 3: Business rule change

Common API anti-patterns (avoid these)

Anti-pattern 1: Overloading fields

Anti-pattern 2: Making optional fields mandatory

Anti-pattern 3: Silent validation tightening

Be liberal in what you accept

Error handling is part of the contract

Example 4: Error response change

How experienced teams evolve APIs safely

A simple checklist before changing an API

Final thought: APIs fail at the boundaries