Playbook · Design and build · 6 steps

Integrating systems or designing an API

Every interface you publish becomes a promise. Decide which promises you can keep.

“Public APIs are forever - one chance to get it right”
— Joshua Bloch, How to Design a Good API and Why it Matters (2006)

Start with step 1 All 82 models for design review

Use as a worksheet

1Information HidingWhich decisions behind this interface should stay free to change?Decompose systems around the decisions most likely to change, and hide each behind an interface.Open
2Hyrum's LawWhich observable behaviour will consumers depend on, whether we document it or not?With enough users, every observable behaviour of your API will be depended on by somebody.Open
3Postel's LawHow strictly do we validate what we accept, and how carefully do we shape what we send?Be conservative in what you send and liberal in what you accept.Open
4Anti-Corruption LayerWhose model wins at this boundary, and where do we translate?Protect your domain model by translating at the boundary with systems whose models you don't control.Open
5IdempotencyWhat happens when a request or message arrives twice?Design operations so doing them twice has the same effect as doing them once.Open
6Eventual ConsistencyHow long can the two sides disagree, and who notices?Replicas may disagree for a while but converge when updates stop. Design the business around the window.Open