CSE Roadmap

Core tier · about 4 hours · 8 parts

Part 7 of 8 · 4 min read

Versioning

Delay breaking changes, catch them early, then phase them in.

Changing an interface without breaking callers

Every team asks how to version. BM breaks the answer into steps.

Step 1: defer breaking changes. Pick technology that hides detail, and train callers to be forgiving. BM's example: the email service needs a customer's first name, last name and email. The response also holds a phone number. If the email code reads only those three fields and ignores the rest, then removing the phone number breaks nothing. If the response is restructured so the names sit inside a "naming" element, a reader that finds fields by name, wherever they are, still works. Martin Fowler calls this a tolerant reader. It follows Postel's law (the robustness principle): be conservative in what you send and liberal in what you accept.

Tolerant reader

A tolerant reader is a caller that picks out only the fields it needs and ignores everything else, so changes it does not care about cannot break it.

Example: the email service reads firstname and email and ignores a new nickname field.

Step 2: catch breaking changes early. Even good technology cannot stop all breaks. BM favours consumer-driven contracts (tests written by the callers, run against the service; his chapter 7 covers them, and they are not covered in this level). Running tests for each supported client library against the latest service also helps.

Step 3: use semantic versioning. A version has the form MAJOR.MINOR.PATCH. A higher major number means incompatible changes. A higher minor number means new functions that are backward compatible. A higher patch number means bug fixes. A caller built against 1.2.0 should work with 1.3.0, may not work with 1.1.0 (it may use something added in 1.2.0), and should expect to change for 2.0.0.

Step 4: coexist endpoints. If a break is unavoidable, avoid making callers upgrade in lock-step. Run old and new versions of the endpoint in the same service, and let callers move over in their own time. When nobody uses the old one, delete it. BM calls this the expand and contract pattern: expand what is offered, then contract. Callers can pick a version by a header or by the address, such as /v1/customer and /v2/customer. BM is torn between them: addresses are obvious and easy to route, but he likes addresses to stay opaque. He warns against keeping many versions: once he had three at the same time, and the extra code and testing were a burden. To cope, he converted each v1 request into v2 and each v2 into v3 inside the service, so retiring an old version meant deleting one clear layer.

A worked example (made up). A customer service moves from name (one string) to first_name and last_name. Step 1: callers read only what they need. Step 2: a contract test shows two callers read name. Step 3: the change raises the major version. Step 4: for six weeks, the service returns all three fields. Callers move over. After week six, nobody reads name, and it is removed.

Interview angle

Answer in your head first, then open it.

How do two services talk?

Request and response over HTTP for answers needed now. Events through a broker for facts others react to. Never through a shared database.

Orchestration or choreography?

Choreography for independent reactions, orchestration for steps that depend on each other. Add monitoring for the implied process.

How do you change an API safely?

Make callers tolerant, add fields and never remove, test contracts, version, run old and new side by side, then retire the old one.

What can go wrong with queues?

Poison messages that crash workers. Set a retry limit, use a dead letter queue, trace with correlation ids.

Check yourself: 1. A caller reads six fields of a response. The service adds a seventh. Does a tolerant reader break? 2. What does a change from 1.4.2 to 2.0.0 tell a caller? 3. Why does BM convert v1 requests into v2 requests inside the service?

Words you will meet

Word Meaning
Database integration Services share and write the same tables
Synchronous The caller waits for the work to finish
Asynchronous The caller carries on without waiting
Event-based collaboration A service announces a fact and others react
Orchestration A central service drives a process
Choreography Each service reacts to others with no centre
RPC A remote call written like a local call
REST A style built on resources and their representations
Resource A thing a service knows about, such as a Customer
Hypermedia Links in a response that show what can be done next
Message broker A system that takes in events and passes them to subscribers
Tolerant reader A caller that ignores fields it does not need
Semantic versioning MAJOR.MINOR.PATCH numbers with fixed meanings
Expand and contract Offer old and new together, then remove the old