“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.
