DEV Community

Cover image for Code Smell 303 - Breaking Changes
Maxi Contieri
Maxi Contieri

Posted on

3

Code Smell 303 - Breaking Changes

When you break APIs without warning, you break trust

TL;DR: You should version your APIs to prevent breaking existing clients when you make changes.

Problems 😔

  • Client applications crashes
  • Integration failures
  • Least Minimal Surprise Principle violation
  • Downtime
  • Broken Trust
  • Deployment rollbacks needed
  • Development time wasted
  • User experience degradation

Solutions 😃

  1. Add semantic versioning
  2. Implement backward compatibility
  3. Create deprecation warnings
  4. Create roadmaps
  5. Use content negotiation
  6. Maintain parallel versions
  7. Communicate changes early
  8. Deprecate features gradually
  9. Document breaking changes clearly
  10. Check deprecated parameters with logging
  11. Test new versions thoroughly
  12. Remove deprecated functionality after sunset

Context 💬

When you modify APIs without proper versioning, you create breaking changes that affect all existing clients.

You force consumers to update their code immediately or face system failures.

You break the implicit contract between API providers and consumers.

Modern software relies heavily on API stability, and introducing breaking changes without warning can create cascading failures across dependent systems.

This is more important today than ever since many IAs build their solutions using existing API documentation.

When you update an API without maintaining backward compatibility, you risk breaking all the applications that depend on it.

This creates instability, frustration, and costly fixes for users.

Clients often tolerate defects on new functionalities, but never a previous stable behavior broken.

Proper versioning ensures smooth transitions and maintains your system's reliability.

Sample Code 📖

Wrong ❌

// user-api-v1.json - Original API response
{
  "id": 317,
  "name": "Mr Nimbus",
  "email": "nimbus@atlantis.com",
  "nationalities": "Brazilian,Canadian,Oceanic"
}

// Later changed to this without versioning:
{
  "userId": 317,
  "fullName": "Mr Nimbus", 
  "emailAddress": "nimbus@atlantis.com",
  "createdAt": "2018-12-09T18:30:00Z",
  "nationalities": ["Brazilian", "Canadian", "Oceanic"]
}

fetch('/api/users/317')
  .then(response => response.json())
  .then(user => {
    // This breaks when API changes field names and data types
    document.getElementById('name').textContent = user.name;
    document.getElementById('email').textContent = user.email;
    // This breaks when nationalities changes from string to array
    document.getElementById('nationalities').textContent 
      = user.nationalities;
  });
Enter fullscreen mode Exit fullscreen mode

Right 👉

// user-api-v1.json - Version 1 (maintained)
{
  "id": 317,
  "name": "Mr Nimbus",
  "email": "nimbus@atlantis.com",
  "nationalities": "Brazilian,Canadian,Oceanic"
}

// user-api-v2.json - Version 2 
// (new structure, backward compatible)
{
  "id": 317,
  "userId": 317,
  "name": "Mr Nimbus",
  "fullName": "Mr Nimbus",
  "email": "nimbus@atlantis.com",
  "emailAddress": "nimbus@atlantis.com",
  "createdAt": "2018-12-09T18:30:00Z",
  "nationalities": "Brazilian,Canadian,Oceanic"
  "nationalitiesList": ["Brazilian", "Canadian", "Oceanic"]
}

// user-api-v3.json - Version 3 
// (new structure, backward not compatible)
{
  "userId": 317,
  "fullName": "Mr Nimbus",
  "emailAddress": "nimbus@atlantis.com",
  "createdAt": "2018-12-09T18:30:00Z",
  "nationalitiesList": ["Brazilian", "Canadian", "Oceanic"]
}

// client-code-versioned.js
const API_VERSION = 'v1';

fetch(`/api/${API_VERSION}/users/317`)
  .then(response => response.json())
  .then(user => {
    document.getElementById('name').textContent = user.name;
    document.getElementById('email').textContent = user.email;
    // V1 handles comma-separated string
    document.getElementById('nationalities').textContent
      = user.nationalities;
  });

// Or with content negotiation
fetch('/api/users/317', {
  headers: {
    'Accept': 'application/vnd.api+json;version=1'
  }
})
  .then(response => response.json())
  .then(user => {
    document.getElementById('name').textContent = user.name;
    document.getElementById('email').textContent = user.email;
    document.getElementById('nationalities').textContent 
      = user.nationalities;
  });
Enter fullscreen mode Exit fullscreen mode

Detection 🔍

[X] Semi-Automatic

You can detect this smell when you find APIs that change field names, remove fields, or alter data structures without maintaining backward compatibility.

Look for client applications that break after API deployments.

Check for missing version headers or URL versioning schemes.

Monitor error logs for sudden spikes in client failures after releases.

Tags 🏷️

  • APIs

Level 🔋

[X] Intermediate

Why the Bijection Is Important 🗺️

You must maintain a stable MAPPER between your API contract and client expectations.

When you break this Bijection by changing the API without versioning, you violate the fundamental principle that clients can rely on consistent interfaces.

You create a mismatch between what clients expect to receive and what your API provides.

This breaks the one-to-one correspondence between API promises and API delivery, leading to system failures and lost trust.

APIs model real-world services. When you break the mapping between your API and the business logic it represents, clients can't reliably interact with your system.

This mismatch leads to defects, downtime, a lack of trust, and a poor user experience.

AI Generation 🤖

AI generators often create this smell when you ask them to "improve" or "update" existing APIs.

They focus on making the API "better" without considering backward compatibility.

You need to explicitly instruct AI tools to maintain existing field names and add versioning when making changes.

They often favor clean design over stability unless explicitly told otherwise.

AI Detection 🧲

AI generators can fix this smell when you provide clear instructions about API versioning strategies.

You should ask them to implement semantic versioning, maintain backward compatibility, and create migration paths for deprecated features.

Try Them! 🛠

Remember: AI Assistants make lots of mistakes

Suggested Prompt: Create API versioning to prevent breaking changes

Conclusion 🏁

You should always version your APIs to prevent breaking changes from impacting client applications.

Even from your first version.

When you maintain stable contracts through proper versioning, you build trust with API consumers and enable smooth evolution of your systems.

Breaking changes are inevitable, but they shouldn't break your clients.

Always version your APIs, deprecate carefully, and communicate proactively to avoid unnecessary disruptions.

Relations 👩‍❤️‍💋‍👨

Disclaimer 📘

Code Smells are my opinion.

Credits 🙏

Photo by Giancarlo Revolledo on Unsplash


APIs are forever, so design them carefully

Martin Fowler


This article is part of the CodeSmell Series.

AWS Q Developer image

What is MCP? No, Really!

See MCP in action and explore how MCP decouples agents from servers, allowing for seamless integration with cloud-based resources and remote functionality.

Watch the demo

Top comments (1)

Collapse
 
vidakhoshpey22 profile image
Vida Khoshpey

Great post, I always had problems with this API I also wanted to use the OpenAI key but I'm banned, maybe one day I can in another country.🙂💻 Keep going 💪🏻

Some comments may only be visible to logged-in visitors. Sign in to view all comments.

👋 Kindness is contagious

Take a moment to explore this thoughtful article, beloved by the supportive DEV Community. Coders of every background are invited to share and elevate our collective know-how.

A heartfelt "thank you" can brighten someone's day—leave your appreciation below!

On DEV, sharing knowledge smooths our journey and tightens our community bonds. Enjoyed this? A quick thank you to the author is hugely appreciated.

Okay