Capability 17 / 18
API & Platform Design
APIs and platforms other teams can build on without reading your mind.
An API is a promise to every team that builds against it — and a platform is a bet that other teams will want to build on it at all. Both only work if the contract is clear enough that a consuming team never has to guess what a field means or what happens when a call fails.
API-first design means the interface is designed before the implementation, versioned deliberately, and documented well enough that someone outside the team can integrate without a Slack thread.
What this looks like in practice
- •API-first design — the contract is designed and reviewed before implementation starts
- •Versioning and backward compatibility treated as a first-class concern, not an afterthought
- •Platform capabilities exposed as self-service, not gated behind a ticket queue
- •Documentation good enough that integration doesn't require a conversation first