The Bezos API mandate.

By Filippo Conforti on March 19, 2024

As a tech legend tells it, Jeff Bezos issued a mandate to all Amazon employees in 2002 that would serve as the foundation for Amazon's huge success. Known as the "Bezos API mandate" or the "Amazon API mandate", this manifesto laid the foundation for the modern API-first development paradigm. According to legend, the mandate is as follows:

  • All teams will henceforth expose their data and functionality through service interfaces.
  • Teams must communicate with each other through these interfaces.
  • 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.
  • It doesn’t matter what technology they use. HTTP, Corba, Pubsub, custom protocols—doesn’t matter.
  • 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.
  • Anyone who doesn’t do this will be fired.
  • Thank you; have a nice day!

That's pretty inspiring, isn't it? Even a bit intimidating, if you put yourself in those developers' shoes. Anyhow, there is a reason why Amazon is Amazon, and why we can all use AWS today.

Although our reality is often quite different, the Bezos API mandate can still teach us something practical we can use in our daily work as ecommerce developers.

Whether you're building Amazon or not, creating and maintaining a custom ecommerce platform requires considerable effort and discipline. In theory, the platform should be regarded as a product rather than an ongoing project. This means code quality, automated tests, documentation, and a well-designed architecture should remain your top priorities.

However, clients rarely request developers to follow an API-first, test-driven, and quality-first approach, instead pushing for a rapid release of new features, sacrificing code quality and documentation in the process. In this way, technical debt increases until businesses are held back from adding new capabilities to their platforms, as developers become unwilling to touch what works in production to avoid breaking anything.

These situations can tempt you to rewrite everything from scratch or buy a solution from some vendor that will solve all your problems. But even if your codebase or architecture isn't the most elegant on earth, there's always value in what works in production. Business logic and workflows that solve real business needs are always extremely hard to beat in terms of business value, so trashing them would be a mistake.

If things get too complex, consider modernizing your stack by exposing your custom code as independent microservices. These microservices can become the core of a new composable stack. A successful architecture can be a combination of best-in-class components that you buy from the market, along with services you and your team build as you go, based on what your business users need.

This is the beauty of composable architectures. This is how we can build an Amazon-like platform without being Amazon. It's never too late to follow the Bezos API mandate, or at least take inspiration from it.

Enjoy the reading?

Subscribe to the newsletter and get a new article delivered to your inbox every week.