"Anyone Who Doesn't Do This Will Be Fired."

Lessons from the Bezos' API Mandate Memo (2002) - ¡APIcryphal! 01

In this first edition of "¡APIcryphal!", I retell the story of Bezos' API Mandate Memo.

Occasionally, among the daily business-as-usual, there emerge moments that change the course of entire industries. The API landscape is a space as molded by legend as any other. While their accuracy to actual events remains debated, these tales remain the cornerstones of hallway tracks and executive talking points. These are API's apocryphal stories - the ¡APIcryphal!

TL;DR: Service-oriented, externalizable architecture capable of transforming a business into a more scalable, future-ready state doesn't just happen. Sometimes, it must be mandated.

Observance

In the second quarter of 2023, Amazon Web Services (AWS) reported net sales of $21.5 billion, generating $5.4 billion in income. Even if you use a competing cloud hosting provider, if you work in software development today, you feel the impact of AWS and their decision making. Despite being a revenue-generating behemoth now, however, AWS's success wasn't always obvious.

Sometime in 2002, Amazon struggled to scale their storefront. In particular, the seasonal demands of e-commerce resulted in spikey computing and storage demands. Jeff Bezos, the founder and then-CEO of Amazon, issued a mandate to all of Amazon's internal development teams. The critical points of this memo were:

  • All teams will henceforth expose their data and functionality through service interfaces.
  • Teams must communicate with each other through these interfaces.
  • No other form of inter-process communication will be 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 didn't matter what technology is used to implement the service (e.g., Java, Perl, etc.).
  • All service interfaces, without exception, must be designed from the ground up to be externalizable. 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.

After threatening immediate termination, Bezos cheekily ended the memo wishing everyone a nice day. Or at least that was the case in the most famous retelling.

And here's the thing: we can't be sure that the Bezos API Mandate Memo actually ever happened. Our primary reference for the memo came from a 2011 internal Google memo by Steve Yegge. To underscore how Amazon understood platforms in a way that Google didn't, he recalled the events of nearly a decade prior.

"But on one occasion — back around 2002 I think, plus or minus a year — he [Bezos] issued a mandate that was so out there, so huge and eye-bulgingly ponderous, that it made all of his other mandates look like unsolicited peer bonuses."

That internal memo got leaked and immediately a copy was submitted to GitHub. Neither Jeff Bezos nor his top engineers have denied the Mandate, which has subsequently entered technology lore. Regardless of the accuracy of the events, the story has changed enterprise software development - and business - ever since.

Interpretation

This directive was a significant departure from how many companies operated at the time. It forced Amazon's teams to think about building scalable, robust, and externalizable services from the outset. This shift in thinking and architecture laid the groundwork for what would become AWS.

Again, from Steve Yegge's retelling:

"Well, the first big thing Bezos realized is that the infrastructure they'd built for selling and shipping books and sundry could be transformed an excellent repurposable computing platform."

AWS, launched in 2006, directly resulted from this architectural shift. It began with the Simple Storage Service (S3) and the Elastic Compute Cloud (EC2). Today, AWS offers a vast array of services (more than 200 at the time of this writing) and has become a dominant force in the cloud computing industry.

Creating distributed systems comes with downsides. While there was a fair amount of documentation on building "Service Oriented Architecture" (or SOA) even then, nobody had done it to the degree or the scale that Amazon attempted. The result was a host of hard-won lessons that the team had to recognize and learn from:

  • Without the proper metrics and reporting, resolving issues becomes very difficult. (This would later lead to the famous quote, "We replaced our monolith with micro services so that every outage could be more like a murder mystery."
  • Every peer team becomes a potential source of a DOS attack, requiring quotas and throttling strategies even for internal traffic.
  • Health routes are nice but insufficient to ensure that a service is running as intended. To avoid surprises, QA needs to be involved in monitoring production.
  • When everything is a service, discoverability becomes a challenge. Subsequently, adopting a service discovery mechanism (like a catalog in a portal) becomes essential. And where there is service discovery, there is service registration.
  • End-to-end debugging when the system consists of other people's code is impossible without a supporting sandbox.
"From the time Bezos issued his edict through the time I left, Amazon had transformed culturally into a company that thinks about everything in a services-first fashion. It is now fundamental to how they approach all designs, including internal designs for stuff that might never see the light of day externally."

The Mandate begat the architecture, and the architecture became the culture - "the way we do things here". It emphasized the importance of thinking big, being customer-centric (even if the customer is an internal team), and focusing on long-term value over short-term gains. This not only allowed Amazon to grow and scale rapidly - it also set the stage for Amazon to offer these services to external developers.

Keys

Key lessons to take from the story of the Bezos' API Mandate Memo include:

  • The Importance of Clear Communication: Jeff Bezos' unequivocal directive left no room for ambiguity. When leaders provide clear direction and stand firmly behind their decisions, it can galvanize an organization to move in the desired direction.
  • Embracing Long-Term Thinking: The benefits of the Mandate, such as the creation of AWS, took time. It underscores the importance of taking a long-term perspective when implementing significant changes. Immediate challenges or setbacks should not deter the overall vision.
  • Not Shying Away from Cultural Transformation: Beyond the technical Mandate, the memo signaled a cultural shift. It emphasized thinking big, being customer-centric, and focusing on long-term value. Institutional change often requires a cultural transformation, where the underlying values and beliefs of the organization align with the desired change.
  • Being Comfortable with Discomfort: The memo showcased Amazon's willingness to disrupt its operations for long-term gain. Successful institutional change often requires organizations to leave their comfort zones and challenge the status quo.
  • Emphasizing Accountability: Bezos clarified that there would be consequences for not adhering to the new Mandate. Leaders can ensure that change initiatives are taken seriously by setting clear expectations and holding people accountable.

Reversal

While the distributed, service-based approach has gained significant mindshare, many successful companies have thrived using "traditional" methods. Chief among these is monolithic codebases. Eschewing service design can be particularly savvy for companies in their early stages or with minimal software needs.

Etsy successfully ran as a PHP monolith for some time before beginning a service transition in 2015. Likewise, GitHub ran as a monolithic Ruby on Rails application for some time by modularizing the codebase, improving database performance, and enhancing caching strategies. It was only recently that GitHub began to introduce some services outside of their core monolith. StackOverflow prides itself on how little hardware is needed to run its monolithic codebase. Shopify is still a Rails monolith.

As Andrei Taranchenko says in his piece, “Death by a Thousand Microservices”:

"The truth is that most companies will never reach the massive size that will actually require building a true distributed system. Your cosplaying Amazon and Google - without their scale, expertise, and endless resources - is very likely just an egregious waste of money and time."

Embracing a service architecture is not inevitable. Some other notable anti-microservice companies are below.

Basecamp

Basecamp is a popular project management and team collaboration software. The company has been vocal about its preference for a monolithic architecture, often arguing the benefits of the "Majestic Monolith". Those benefits include faster development, easier testing, and fewer complexities than distributed systems. Basecamp continues to serve millions of users with this monolithic architecture successfully.

Segment

Now owned by Twilio, Segment is a "customer data platform". It attempts to tie all of a company's data together to present the entire history of each customer relationship. Microservices were first introduced to solve isolation problems within Segment's monolith. However, as the company integrated with more services, the operational overhead of supporting microservices became too much to bear. The company decided to move back to a monolithic codebase soon after.

Legacy

Despite (allegedly) happening more than twenty years ago, the Bezos Mandate Memo continues to be cited in discussions about microservices, platform thinking, and the importance of clear, decisive leadership in driving transformational organizational change.

We must venture beyond the surface-level accolades in dissecting the oft-cited Bezos' API Mandate Memo. For one, the Mandate is a testament to the power of constraints as catalysts for innovation. It's a lesson for all of us in the tech realm, a reminder that sometimes, the most stringent boundaries can lead to the most profound breakthroughs. Secondly, we also must consider the human element; any seismic shift, no matter how visionary, brings with it the inertia of established practices. The Mandate wasn't merely a directive but a challenge, a gauntlet thrown to teams comfortable in their routines.

Yet, one must caution against viewing this as a universal blueprint. What worked for the behemoth that is Amazon, given its unique culture and challenges, isn't a panacea for all digital transformation. The Mandate's success hinged on its vision and on relentless execution. Not all organizations share the same wherewithal to seeing change through the inevitable challenges.

Subscribe to Net API Notes

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.
jamie@example.com
Subscribe