An API Is a Promise Before It's an Interface
A public API looks like a technical decision: which endpoints, which verbs, what shape the response takes. Read it that way and you’ll miss the actual architecture, which is a promise — made to people who don’t work for you, can’t see your roadmap, and will build real things on top of whatever you say you’ll keep stable.
Every field you expose is a commitment. Every rate limit is a statement about how much you trust a stranger’s use case. Every version you deprecate breaks something you never saw being built, for a reason the person on the other end will never fully understand — because the reasoning happened entirely on your side of the interface.
This is why the hardest part of API design was never the schema. It’s deciding what you’re actually promising, and to whom. A generous, well-documented API earns something a private one never can: an ecosystem that extends your product for you, unpaid, because they trusted the contract enough to build on it. That trust took years to earn and can be spent in a single announcement — a pricing change, a rate-limit tightened overnight, an endpoint quietly removed. The technical change is often small. The trust change is not, because everyone downstream now has to ask what else might move without warning.
None of this shows up in an architecture diagram. A diagram will happily show you the endpoints, the auth flow, the data model — and say nothing about who is relying on the shape staying the same, or what it costs them if it doesn’t. That’s the same gap the diagram was never the deliverable makes everywhere else in this practice: the artefact captures the structure, not the obligation the structure represents.
So the real architectural question isn’t “what should the API expose?” It’s “what are we willing to be held to, by people who trusted us enough to build on it — and are we designing the interface to honour that, or just to be convenient for us to change later?”
An API outlives the decision that shipped it. Design it like a promise, because to everyone depending on it, that’s exactly what it is.