REST API Basics: Breaking Changes

When designing REST APIs, one of the biggest challenges is avoiding breaking changes, modifications that force existing clients to update their code. A well-designed API should evolve over time without suddenly breaking consumers who rely on it.

🔴 What is a Breaking Change?

A breaking change is any modification in your API contract (endpoints, request structure, response format, or behavior) that makes previously working client applications fail.

For example:

• Changing /users/{email} to /user/{id}/prefs without versioning

• Renaming fields like firstName → fName

• Changing the type of a property (e.g., “age”: “37” → “age”: 37)

• Removing values from an enum (“country”: “ROU” → only “ESP” or “BEL”)

• Altering content type (from application/json to application/xml)

---

🚩 Common Examples of Breaking Changes

1. Endpoint Changes

✅ /users/{id} (stable)
❌ /users/{email} → /user/{id}/prefs (clients must adapt)

2. Required vs Optional Fields

✅ Adding an optional field like “middleName”
❌ Making a previously optional field required (e.g., “address”)

3. Data Type Changes

✅ “age”: “37” (string, consistent with old clients)
❌ “age”: 37 (number, breaks clients expecting a string)

4. Enum & Value Restrictions

✅ Supporting multiple values: “currency”: “EUR” | “USD”
❌ Removing support: “currency”: “EUR” only

5. Date/Time Format

✅ “2023-03-01T00:00:00Z” (ISO-8601 standard)
❌ “03/01/2023” (ambiguous, regional differences)

---

📝 Recap

Here are some examples of breaking changes in REST APIs you should avoid.

---

📌 Key Takeaway

Breaking changes are sometimes unavoidable, but with careful design, versioning, and communication, you can minimize disruption for your API consumers.

Think of your API as a contract: once you publish it, others depend on it. Treat it with care.

---

👉 Want to dive deeper? Check out my other REST API posts:

Versioning Your REST API Made Easy: Tips and Tricks

And don’t forget to subscribe to the blog for more Java & backend insights 🚀