Breaking Change in API Versioning

A breaking change modifies an API contract in a way that can make existing clients fail, stop compiling, or behave differently. Java backend engineers should identify such changes early and use compatible evolution or explicit versioning when necessary.

An API contract includes the information clients depend on, such as endpoint paths, HTTP methods, request and response formats, required fields, status codes, and behavioral guarantees. A change is breaking when a client that worked against the previous contract may no longer work correctly without modification.

Common breaking changes include removing an endpoint, renaming a response field, changing a field from optional to required, changing a data type incompatibly, or altering authentication requirements. Changing documented behavior can also be breaking even when the URL and JSON structure remain unchanged.

For a Java backend, breaking changes can affect both HTTP clients and consumers of Java libraries. With REST APIs, the safest default is usually additive evolution: introduce a new optional field or endpoint while continuing to support existing clients. If an incompatible change is unavoidable, teams commonly introduce an explicit API version or migration period.

Semantic compatibility matters too. For example, changing a successful operation from returning `200 OK` to requiring clients to handle a different status can break clients that assume the old response. Backward compatibility should therefore be evaluated from the consumer's perspective, not merely by checking whether the server still starts.

Key points

• A breaking change can make previously working clients fail or behave incorrectly.
• Removing or renaming contract elements is a common source of incompatibility.
• Making an optional request field required can break existing callers.
• Prefer additive, backward-compatible API evolution when practical.
• Use explicit versioning or migration strategies when incompatible behavior is required.

Interview questions

What is a breaking change in an API?

A breaking change alters an API contract in a way that can prevent an existing client from working correctly. Examples include removing an endpoint, renaming a response field, or making a previously optional request field required. It can also involve changing behavior or status-code expectations. The key question is whether an existing consumer must change to continue working.

Is adding a new field to a JSON response a breaking change?

Usually, adding a response field is backward-compatible for clients that ignore unknown fields. However, compatibility depends on how consumers deserialize and validate the response. A client that rejects unknown properties could be affected. Therefore, the client ecosystem and serialization rules should be considered rather than assuming every addition is automatically safe.

Why can making an optional request field required be a breaking change?

Older clients may omit the field because the previous contract allowed them to do so. If the server starts rejecting those requests, those clients stop working without any client-side deployment. This changes a previously valid request into an invalid one. A safer approach is often to introduce the field as optional and migrate consumers before enforcing it.

How would you evolve a REST API without breaking existing clients?

I would prefer additive changes, such as new endpoints or optional response fields, while preserving existing request and response semantics. For changes that cannot be made compatible, I would introduce a separate version or contract and give consumers a migration path. I would also document deprecations and monitor usage before removing the old behavior. Contract tests and compatibility testing can help detect accidental breaking changes.

Can changing an HTTP status code be a breaking change?

Yes, if existing clients depend on the previous status-code contract. For example, a client may treat `404` as an expected business condition but fail on a newly introduced `410`, or it may only handle a documented success code. Compatibility therefore includes protocol behavior, not just JSON schemas. The impact should be evaluated against actual consumer assumptions and documented guarantees.