3 commandments that should drive every API strategy

In the early 2000s, companies like Amazon, eBay, and Salesforce drove a trend toward standardizing interfaces among web applications. The result was a complete overhaul of how applications were developed and integrated, thanks to a growing network of open web APIs that anyone could consume.

During this period, Amazon founder Jeff Bezos wrote a memo to his employees that came to be known as the “Bezos API Mandate.” According to secondary sources, this mandate included two strategic requirements that any IT leader should consider when seeking to maximize the value of their development teams’ efforts. The first is that all interfaces among software developed by any team should be through APIs; the second is that teams should write internal APIs as if they were to be consumed by people outside the company.

This approach goes a long way toward explaining how Amazon was able to externalize its computing infrastructure — first to Merchant.com, the company’s ecommerce-as-a-service platform for retailers to build their own online stores, and then to Amazon Web Services, a broader offering that has since taken a life of its own.

Fast-forward to 2023 and IT leaders have distilled many more lessons about effective API development and use over the past twenty years. Much of what has been learned is catalogued by the MACH Alliance, a global consortium of nearly 100 technology vendors that promotes “open and best-in-breed enterprise technology ecosystems,” with an emphasis on microservices and APIs.

Here, MACH Alliance members and other IT leaders offer the following three commandments that should underpin any API strategy. These principles not only ensure software systems work well together, but also that teams work together in service of the organization’s overall software development strategy. After all, just as with APIs, when one group of people provides a service to other groups, promises must be clear, and boundaries respected.

1. Adopt an API-first approach

The most effective way to maximize your API strategy is to take what is known as an “API first” approach, in which APIs are prioritized as the building blocks of your software development strategy from the ground up.

API-first organizations focus more on interfacing than integrating. They define APIs first, including the service they perform, the inputs they take, and the outputs they produce, before writing any other code. In this way, rather than integrating various software components to build a monolithic application, they use componentized services that are made available to an ecosystem through their APIs. Organizations that do not use an API-first approach develop their software before designing their APIs, which limits their usefulness, says Casper Rasmussen, global SVP of technology at Valtech and president of the MACH Alliance.

“API first is about designing interfaces that are versatile, rather than specific to a particular use case,” Rasmussen says. “If you’ve bolted APIs on top of your existing legacy software, you are not API first — at least not historically. The legacy software carries assumptions about what it does, to whom, and in what use case. API first is much more versatile, much more generic. Think about, for instance, an API strategy that assumes the consumer is going to be a web client. It communicates HTML, which makes it difficult to use in other environments.”

An API-first approach enables organizations to take full advantage of microservices architecture, a variant of service-oriented architecture (SOA), in which applications are structured as collections of loosely coupled services. One company that has adopted an API-first approach is The Lego Group — fittingly, given that the concept mimics the Legos product set, where standard interfaces on the bricks enable users to piece together a larger whole.

“Our strategic priority is to build loosely coupled systems, supported by our product teams who build and operate APIs to expose their services,” says Niall Edwards, vice president of marketing and channels technology at The Lego Group. “Our Lego.com technology platform has been entirely microservices- and API-based for a number of years now and we are now propagating this approach across all of our technology areas. We are now bringing this approach to the more monolithic enterprise systems.”

The Lego Group offers a perfect example of how the API-first approach favors microservices, rather than larger, more complex functionality. New APIs should perform narrowly defined services that can be used by a variety of applications. Older systems can be retrofitted with APIs in a way that enables applications to consume legacy services as if they were newly developed.

As legacy technology investments come up for replacement, CIOs would be wise to ensure new vendors are brought in only if they deliver microservices and conform to API-first principles.

2. Develop an API policy and enforce it

To ensure loose coupling and high coherence among software components developed by different groups—both internal and external—a common API policy is necessary.

The policy should indicate that some services are performed centrally by IT, even as most API work is implemented independently by a variety of development teams. For example, to ensure consistency, access control should be centrally managed, with one identification and authentication scheme to be used by all APIs. Data format should also be centrally managed to ensure uniformity. And finally, service level agreements (SLAs) should be defined and controlled by IT. For example, you might say that for anything customer facing, the APIs should respond within 50 milliseconds.

“If there is no clarity on who is responsible for what, then its chaos and no one knows the source of truth,” says Edwards. “The enterprise data model must clearly indicate who is accountable for which data. Users of that data need to know they can cache it and use it but never change it. Changes to data occur only back at the source, and those changes should be discoverable and exposed to all consumers.”

APIs needed to be backed by microservices to be most effective. CIOs should define APIs with this assumption and then either build the service internally or select vendors that provide services that adhere to this approach.

“APIs should be independently callable, stateless, and idempotent,” says Kelly Goetsch, chief strategy officer at commercetools and author of four books on APIs and microservices. This means that an application can use an API without having to call another first, and that values internal to the service are not changed in a way that causes it to produce a different result each time it’s called. For example, you can invoke an API to add to a cart several times — and if it is idempotent, it will act the same way each time it’s invoked.

Finally, the policy should ensure there is no distinction between internal-only APIs and external APIs. “One of the brilliant parts of the Bezos Mandate was to say that APIs need to be externalized by default,” says Rasmussen. “And if you look at AWS, which started as an internal project, they made it available to the outside world by just changing the access on what was already being used inside the company.”

Once an API policy is put in place, the key is to make sure all teams adhere to it. With so many moving parts, connections, and data in transit, this is a crucial facet no IT leader should overlook.

3. Build and maintain a catalog of APIs

With such a wide array of services likely to be necessary to fulfill your API vision, it’s also essential to index the APIs your organization is creating, as well as those your organization is likely to rely on third parties to provide.

“CIOs should develop a catalog of APIs and a strategy for managing that catalog,” says Goetsch. “The catalog should define APIs and include all functionality the enterprise needs. Then you can decide whether to build or buy the software that provides those services.”

While the catalog should be centrally maintained, the responsibility for implementation should be left with individual teams or external vendors. But those who develop the services must be bound by what’s defined in the catalog, Goetsch says.

“The teams implementing the APIs can pick their database, and a lot of other things,” he says. “But then if they mess up, hold them accountable. You can very quickly and easily determine if a team is managing it correctly. If the APIs are going down, then you know you got a problem.”

The central catalog should be well documented and be accompanied by discovery tools that enable internal and external users to find APIs based on a description of their needs or a set of keywords. “The Lego Group has invested in centralized discoverability tools to help developers find each other’s APIs and use them to compose a bigger product, just like people do with the Lego bricks,” says Edwards.

By adhering to these three commandments and heeding the wisdom gained through years of experience, IT leaders can build a framework that ensures a clear path to every service. Consumers can count on a solid interface and producers get the freedom they need to build services. Each side can innovate in their own time.