The Bezos API Mandate

A famous internal directive at Amazon, ~2002, reportedly issued by Jeff Bezos. It mandated that every team must expose its data and functionality only through service interfaces, with no other form of inter-team communication. The org-scale equivalent of Headless Architecture.

The memo is the single most-cited piece of writing for "headless thinking at organisational scale." Birthed AWS as a side effect when Amazon realised its internal services could be sold externally.

The text isn't officially published. The widely-circulated version comes from Steve Yegge's Google Platforms Rant (2011), where Yegge — a former Amazon engineer — recounts the mandate while criticising Google's contemporaneous lack of similar discipline.

The five-and-a-half rules

Per Yegge's recollection:

1. All teams will henceforth expose their data and functionality through service interfaces.
2. Teams must communicate with each other through these interfaces.
3. There will be no other form of interprocess communication allowed: no direct linking, no direct reads of another team's data store, no shared-memory model, no back-doors whatsoever. The only communication allowed is via service interface calls over the network.
4. It doesn't matter what technology they use. HTTP, Corba, Pubsub, custom protocols — doesn't matter. Bezos doesn't care.
5. All service interfaces, without exception, must be designed from the ground up to be externalizable. That is to say, the team must plan and design to be able to expose the interface to developers in the outside world. No exceptions.
6. Anyone who doesn't do this will be fired. (The famous "joke" sixth rule.)

Genuine internal-comms tone. Yegge says he was there for it. The mandate is plausibly the single most-load-bearing decision in Amazon's commercial history.

What this enabled

Without realising it at the time, Amazon spent a few years internally building services that:

• Were genuinely modular (no shared memory, no back-doors)
• Had stable interfaces (because internal teams depended on them)
• Were designed for external exposure (per rule 5)
• Used real wire protocols (HTTP, etc., per rule 4)

When the realisation hit ("we could sell these to others"), AWS was already most of the way there. EC2 launched 2006; S3 launched 2006; the internal services predated both by years.

The lesson: the architectural discipline pays off even before the commercial application is obvious.

Why this maps to mxr / lazydap

The mandate is org-scale. The same idea works at single-developer scale:

• All clients (TUI, CLI, agent skill, web bridge) talk to the daemon only through the IPC contract.
• No back-doors. The TUI cannot reach into daemon-internal types. Cargo's dependency graph enforces this.
• The protocol is designed to be externally consumable. Anyone can build a third-party client in any language by implementing the IPC contract.
• The technology underneath (SQLite, Tantivy, providers) is irrelevant to clients. Same as Bezos's "doesn't matter what technology."

The discipline scales down. A solo developer can apply Bezos-style rules to their own system and reap the same architectural benefits at a smaller scale.

Critiques and limits

The mandate isn't universally praised:

• Engineering overhead. Every internal interaction becomes a network call. Latency adds up; debugging cross-service flows is hard.
• Distribution-first means distributed. Once everything is a service, you have a distributed system whether you wanted one or not. Distributed systems are harder.
• Communication cost. Teams need to coordinate on interface changes; otherwise interfaces become barriers, not abstractions.
• Microservices critique applies. Many subsequent organisations overshot Amazon's pattern, ending up with chatty service meshes that performed worse than monoliths.

For local tools (mxr, lazydap), the network-cost critique doesn't apply — Unix sockets are essentially free. The architectural discipline transfers; the operational pain doesn't.

Why I (the user) keep arriving at this

Reading the mandate is the experience of recognising that someone wrote down what you'd been doing without naming it. The pattern feels like common sense once you've internalised it: of course your TUI shouldn't reach past the protocol; of course your daemon shouldn't have backdoors; of course the IPC contract should be designed for external consumers.

Pre-mandate (in any context, including solo work), it's surprisingly easy to justify backdoors. "Just for now, just for performance, just because the abstraction is awkward." Post-mandate, the discipline is the architecture. Once you've felt the win — adding a new client is a small project, not a refactor — the mandate stops feeling like overhead.

See also

• Client-Agnostic Cores — the synthesis
• Headless Architecture — the architectural form
• API-First Design — the methodology
• Mxr · Lazydap — solo-scale applications of the same discipline
• Steve Yegge's Google Platforms Rant: https://gist.github.com/kislayverma/d48b84db1ac5d737715e8319bd4dd368
• Nordic APIs writeup: https://nordicapis.com/the-bezos-api-mandate-amazons-manifesto-for-externalization/