Skip to main content

Request and response compatibility point in different directions

What This Concept Is​

Compatibility is a relationship between producers and consumers under a promised contract. For existing clients calling an upgraded server, every previously valid request must remain accepted. For responses, every output the upgraded server may emit must remain understandable by the old consumer. These inclusion tests point in opposite directions.

Why It Matters Here​

A schema diff can say “enum extended” without answering whether that enum appears in a request or response. A change can help new callers while breaking old readers. The original migration lab needs executable counterexamples, not just labels such as additive or breaking.

Concrete Example​

An old request permits mode="a". A new request permits "a" or "b". Old requests remain valid. But if a response field previously contained only "a", emitting "b" can break an old consumer that accepts only "a". The same enum edit has different consequences depending on who reads the field.

An old request allows an empty object. The new request requires region="a". The empty object is the failure witness: it was accepted before and is now refused. Representing “no witness” with an empty dict would lose this evidence; the lab uses None for that distinct meaning.

Common Confusion / Misconception​

Adding a field is not automatically safe for every client. A strict closed-object reader rejects unknown response fields; a tolerant reader may ignore them. The declared consumer behavior matters. Conversely, accepting an optional new request field does not make old providers understand new clients during rollback.

How To Use It​

Write separate request acceptance and response emission contracts. Name the old consumer, old provider, new consumer and new provider. Check all combinations required during the migration and rollback window; new-to-old operation is a separate promise from old-to-new operation. Preserve actual consumer fixtures as well as schema tests.

Check Yourself​

Why does widening a response enum differ from widening a request enum? Why can making a required response field optional break a reader? Is an empty object always an invalid payload?

Mini Drill or Application​

Classify optional/required changes, field removal and enum narrowing in both directions. Predict a concrete witness before running the archive. Add a strict and a tolerant consumer to the original HTTP lab and explain the different results for an additional response field.

Read This Only If Stuck​

API Design Patterns — compatibility and versioning. Google AIP-180 provides compatibility guidance; the lab's finite strict-object model is an explicit teaching simplification rather than a universal API policy.