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

Can an old client read the new response? Parse Validate Handle Respond

Scroll sideways to see the full diagram.

  1. Decode the input into values.

    Step 1 of 4
  2. Apply type and length rules.

    Step 2 of 4
  3. Run the operation on a valid name.

    Step 3 of 4
  4. Return 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

Run the browser experiment

Optional local lab

Run the contract fixtures. Add cases for a blank name and a list. Write down the response an old client expects.

Open the local exercise files

Check yourself

Which change can break an old reader expecting text?

Not quite. The reader still finds its original text field. Re-read that part ↑

Right. An API contract specifies methods, fields, validation, status codes and compatibility.

What does a successful parse establish?

Right. Field validation follows parsing.

Not quite. Field validation follows parsing. Re-read that part ↑

How can a new client safely read responses from the old server?

Not quite. An older producer cannot supply a field it never implemented. Re-read that part ↑

Right. An older producer cannot supply a field it never implemented.

Sources

What you now know

An API contract specifies methods, fields, validation, status codes and compatibility.