Skip to content

Mastering API Architecture: contract first, test second

James Gough, Daniel Bryant and Matthew Auburn · O'Reilly, first edition, 2022
4 de mayo de 2026 por
Mastering API Architecture: contract first, test second
Andrés Briñez

The book walks the full cycle: design an interface with its specification before writing it, test it in layers, put it behind a gateway, secure it, and let it evolve without breaking whoever already depends on it. It runs one case study through the whole text and records decisions at the end of each stretch.

What I took from it

The first habit is decision records. Every architectural choice gets written down with three things: the context it was made in, the option chosen, and what is being accepted in exchange. It takes half a page and it answers the question that arrives months later, when somebody wants to know why it was built this way and the honest answer is that nobody remembers. Since I started writing them, they go out alongside the map.

The second is contract testing. It is the idea that changed my integration work most: instead of testing the whole system end to end, you write down exactly what the consumer expects and verify it against the provider. When the other team changes a field, a test finds out rather than a user, and that difference is what separates an integration you can maintain from one you have to watch by hand.

The third is where the cross-cutting concerns belong. Authentication, rate limits and logging go at the gateway, not scattered through every service. When those are spread out, changing one rule means touching ten places and one always gets missed.

What I left out

The service mesh and much of the platform decision-making. The book assumes a team and infrastructure of your own; working alone against an ERP that already publishes its own interface, you find half those decisions have been made for you. I also left the enthusiasm for decomposing systems into services, which almost always gets proposed before anyone has understood the domain.

A 2011 database handbook: normalisation is still the part that does not expire
José Manuel Piñeiro Gómez · Editorial CEP, 2011
WhatsApp