CoursesBackend engineering from first request to production
Puzzle 5 · 6 of 18
Can an old client read the new response?
Define the shape and meaning of a request before changing it.
All puzzles in this course
The problem
Your route accepts a bookmark. A newer client sends an extra color field. Must an older server reject the request?
See it
Scroll sideways to see the full diagram.
Decode the input into values.
Step 1 of 4Apply type and length rules.
Step 2 of 4Run the operation on a valid name.
Step 3 of 4Return a documented status and shape.
Step 4 of 4
The building block
An application programming interface (API) is the interface a program offers its callers. A contract is an agreement about what each side accepts and returns. First parse the bytes as JavaScript Object Notation (JSON), a text format for objects, arrays and simple values. Then validate the fields the operation needs. For this exercise a missing or blank name fails validation, while unknown fields are ignored. An additive field works only when readers tolerate it. Changing a field from text to a list can break existing readers even when the status stays 200. Document the rule and test both client versions.
Walk one body through both checks
A lone opening brace cannot be parsed, so the fixture returns 400 before field validation. A body containing a name field set to a list of names parses successfully; the name has the wrong type, so the fixture returns 422. A body with the text fields name (river) and color (blue) passes because the required name is text and this reader ignores the extra field. For a version change, test old client with new server and new client with old server separately. A new client that requires color will still fail when the old server omits it.
Try it
Optional local lab
Run the contract fixtures. Add cases for a blank name and a list. Write down the response an old client expects.
Check yourself
Sources
What you now know
An API contract specifies methods, fields, validation, status codes and compatibility.
Answer every question above correctly to unlock the next puzzle.
Something wrong or unclear on this page? Tell me: a puzzle that didn't click is a bug in the puzzle.