Skip to content

API Design Patterns: an integration is a contract, not a favour

JJ Geewax · Manning, 2021
3 de octubre de 2025 por
API Design Patterns: an integration is a contract, not a favour
Andrés Briñez

Geewax writes from Google and from resource-oriented design: instead of inventing verbs, you name things and apply a small set of standard operations to them. On that base he works through the problems that always turn up: how to update one field without trampling the others, what a ten-minute operation returns, how to page through a hundred thousand records, how to delete something another system still points at.

What I did with it

It changed how I write the integration half of an architecture map. I used to draw systems joined by arrows; now every arrow carries its contract: which resource, which operations, who owns the data, and what happens when the other side does not answer. An arrow without a contract is a wish with a line through it.

The compatibility rule is the one that saves me the most argument. Adding a field is safe; removing it, renaming it or changing what it means is not, however loudly someone says nobody uses it. In any company there is always a connected spreadsheet that nobody remembers building.

And the long-running operations pattern changed what I promise: a process that takes time — a bulk load, a call to a government service, a reconciliation — does not return the result, it returns something you can ask about later. Modelling that from the start avoids the worst possible conversation, the one about the frozen screen.

What I left out

The level of ceremony. These guidelines were written for interfaces used by thousands of teams over years; a connector between two systems inside a mid-sized company does not need the whole apparatus, and applying it in full becomes a cost the client pays for nothing. I take the vocabulary and the compatibility rules, and leave the rest on the shelf.

AI-Powered Business Intelligence: written before the earthquake, still useful
Tobias Zwingmann · O'Reilly, 2022
WhatsApp