Definition
Have you ever updated an app on your phone and suddenly found that something you used to do no longer works? Maybe a button disappeared, or a feature behaves completely differently? That frustrating experience is essentially what happens when an API makes a “breaking change” - except instead of regular users, it’s developers and their applications that get caught off guard.
A breaking change is any modification to an API that causes existing applications using that API to stop working correctly. Think of it like this: if you’ve been sending letters to a friend at a specific address for years, and one day they move without telling you, your letters will start coming back as undeliverable. The “contract” you had about where to send things has been broken.
In the world of APIs, these contracts are very precise. When developers build applications that rely on an API, they write their code expecting certain endpoints to exist, data to come back in a particular format, and behaviors to remain consistent. A breaking change violates one or more of these expectations. It could be something as dramatic as removing an entire feature, or as subtle as changing whether a field is optional or required. Either way, the result is the same: code that worked perfectly yesterday suddenly fails today.
Example
Real-World Scenario 1: The PayPal Authentication Overhaul PayPal once changed their authentication system from simple API credentials to OAuth 2.0 tokens. Every merchant who had integrated PayPal had to rewrite their authentication code, update how they stored credentials, and deploy new versions of their payment systems. This wasn’t a bug fix or a minor tweak - it was a fundamental change to how every single API call needed to be made.
Real-World Scenario 2: The Twitter API Restructuring When Twitter (now X) restructured their API, many third-party apps that had been working for years suddenly couldn’t fetch tweets, post updates, or access user information. Developers had to scramble to understand the new endpoints, update their code, and sometimes completely redesign their applications.
Real-World Scenario 3: The Facebook Graph API Updates Facebook regularly deprecates older versions of their Graph API. Apps built on version 2.0 might stop working when that version is sunset, requiring developers to update to version 3.0 or later. This affects everything from login buttons to social sharing features across millions of websites.
Real-World Scenario 4: Stripe’s Payment Object Changes
When Stripe changed how payment objects were structured, applications expecting to find customer information in one location suddenly found it nested elsewhere. What was once response.customer.email might become response.data.customer_details.email_address, breaking every piece of code that relied on the old path.
Analogy
The Home Renovation Metaphor: Imagine you’ve lived in the same house for 10 years. You know exactly where the light switches are - you can flip them in the dark without thinking. One day, the landlord decides to “modernize” and moves every single switch to new locations, changes some from switches to motion sensors, and removes a few lights entirely. You come home that night and suddenly can’t navigate your own house. That’s a breaking change. Sure, maybe the new setup is “better,” but no one warned you, and all your muscle memory is now useless.
The Restaurant Menu Analogy: You’ve been ordering “the usual” at your favorite restaurant for years - a #7 combo that you love. Then they redesign the menu: #7 is now something completely different, your old favorite has been removed entirely, and the items you used to get are now scattered across three different menu sections with new names. The restaurant might say “we improved the menu,” but for you, it’s chaos.
The Language Evolution Example: Think about how languages change over time. If someone from 1825 tried to read a text message today, they’d be lost - not because the language is “broken,” but because the shared understanding of words, abbreviations, and conventions has changed. Breaking changes in APIs are similar: the “language” the API speaks has changed, and old “speakers” (existing applications) can’t understand it anymore.
The Highway System Comparison: Picture a highway system where trucks have been using a specific exit for deliveries for 20 years. One day, the city closes that exit permanently and moves it 10 miles down the road without updating the GPS systems or signs. Thousands of delivery trucks suddenly can’t complete their routes. The city might have had good reasons (construction, safety, efficiency), but the sudden change breaks the entire logistics system that depended on that exit.
Code Example
// Breaking changes examples
// ❌ Removing endpoint
DELETE /v1/users/{id} // Removed in v2
// ❌ Changing HTTP method
// v1: POST /login
// v2: GET /login // BREAKS clients using POST
// ❌ Changing response structure
// v1
{
"products": [...]
}
// v2
{
"data": {
"products": [...]
}
} // BREAKS clients accessing response.products
// ❌ Making optional field required
// v1: POST /orders {"productId": 123}
// v2: POST /orders {"productId": 123, "quantity": 1} // quantity now required
// ❌ Changing error code format
// v1: {"error": "INVALID_TOKEN"}
// v2: {"error": {"code": "AUTH001", "type": "InvalidToken"}}
// How to communicate breaking changes
[HTTP/1.1](https://reference.apios.info/terms/http-1-1/) 200 OK
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
[Deprecation](https://reference.apios.info/terms/deprecation/): true
Link: <https://api.company.com/docs/migration/v1-to-v2>; rel="deprecation"
{
"warning": "This endpoint will be sunset on 2025-12-31",
"migrationGuide": "https://api.company.com/docs/migration/v1-to-v2"
}