Which API changes are breaking

API design: REST, HTTP, GraphQL and gRPC Mid-level Python 3.13+ PostgreSQL 17+ Reviewed 31 Oct 2026 By Best Latest Apps

Pick the fix

Which change is safe to ship without a new version?

OptionsAdding an optional note field to the order responseMaking customer_id required in POST /ordersChanging total from integer cents to a decimal stringReturning 422 instead of 400 for validation errors

Hint 1 of 1

Could a correct old client fail?

Choose an answer, then open Show answer below to check it.

Show answer

Answer: A Adding an optional note field to the order response

Correct. Clients that ignore unknown fields keep working.

A change is backward compatible when every existing request and parser still works. New optional response fields pass that test as long as clients ignore fields they don't know, which is the usual rule.

Why not the others?

B Making customer_id required in POST /orders. Old clients that omit it now fail.
C Changing total from integer cents to a decimal string. Type change: old parsers break.
D Returning 422 instead of 400 for validation errors. Clients that handle 400 miss the new code.

30-second answer

A change breaks clients if a correct old client could now fail. For responses: removing or renaming a field, changing its type or meaning, or making it nullable are breaking; adding a field usually isn't. For requests: adding a required parameter, tightening validation, or removing an accepted value are breaking; adding an optional parameter isn't. Status code and error format changes are breaking too.

Practise saying it · 30 s. No recording, just a timer

What counts as a breaking change?

Say your answer out loud, then check which of these points you covered:

Old correct client fails
Remove, rename, retype
New required input
Codes and errors too
Schema diff in CI

Deep dive

Postel-style tolerance on the client (ignore unknown fields) is what makes adding fields safe.

Changing default sort order or page size can break clients that relied on it.

Run a schema diff (for example on the OpenAPI document) in CI to flag breaking changes.

Deprecate first, measure usage, then remove in a new version.

Common mistakes

Treating a nullability change as harmless.
Tightening validation in a patch release.
Assuming no one depends on undocumented behaviour.

Senior take & follow-ups

Use the 'correct old client fails' test, split request vs response, and mention schema diffs in CI.

Follow-up questions

Think of your answer first, then open the hint.

Is adding an enum value breaking?
Show hint
It can be for clients with exhaustive switches; say enums are extensible from day one.
Is a faster response breaking?
Show hint
No, but changed ordering or timing assumptions sometimes are.

Suggest a fix if something here is wrong or out of date.