Talking about APIs internally can sometimes be difficult for managers with convincing their organization to have an API-mindset at the core of their digital strategy.
This is why we have gathered three metaphors to help readers with presenting convincing arguments to stakeholders about why APIs can be game changers in accelerating digital transformation and get faster rewards from transformation efforts. Please remember that metaphors are always incomplete, but they can start a longer conversation about what an organisation needs to think about adopting APIs.
For Technologists and IT people : The Restaurant Menu
Many IT functions have, unfortunately, been under increasing pressure to deliver at speed and lower cost; struggling to deliver IT capabilities at the pace of the business’s expectations. For many reasons including past technology choices, they are stuck with technical debt that sucks most of their budget and slows their ability to react to business demands. A contributor to this technical debt is that they did not (or could not) at the time use APIs as an interface to represent It capabilities in a business perspective. Programming interfaces were coupled with backend technologies (CRM, ERP, Databases, etc) and so changing a product or a technology broke all integration and entailing huge IT refactoring costs that never materialised. This is a reason why even Amazon.co (the company behind AWS) still had Oracle databases in 2019 that were implemented in 1997!
This is where the restaurant menu metaphor comes into action.
The menu of a restaurant is a dining experience, a projection of what customers want to eat representing capabilities of what the kitchen can deliver, and what you can get from the service of the waiter to your plate.
If well designed around the user experience, the menu is independent of kitchen utensils and furniture or the origin of ingredients; and any waiter can deliver the service.
So a customer- or business-centric menu liberates the design of the architecture of the kitchen behind, enabling the cook to organize, change, maintain or replace cooking appliances the way they want, replace ingredients when moving to other suppliers, even outsource some parts, as long as what is on the menu can be delivered.
A poorly designed menu would have included extraneous information to deliver a suitable dining experience for the customer and missed necessary business abstraction. For instance, you could read “Roasted Chicken with potatoes cooked with GN1/1 Vesta oven”. Clearly, a change to the GN1/1 Vesta Oven will break the menu interface, and all customers’ interactions with the menu. You would need to retire all menu from the front office area, but also all menu distributed in all hotels chains, companies lobbies, website, 3rd-party apps etc… This is assuming the diner never needed or wanted to know in what their meal was cooked on in the first place
So APIs must be designed like menus, meaning designed towards business capabilities that end users want, more than what the kitchen looks like. That will provide IT systems and IT managers with earlier relief from technical debt; enabling them to refactor architecture, vendors software and services the way they want as long as they are still able deliver what the menu exposes.
For Business, Product (and also IT) People
For business and product people, a metaphor that works well is the lego brick. This metaphor has the advantage of showing that if APIs are thought of as building bricks, with interfaces that are consistent, they will be able to be assembled mentally and technically by anyone in the company to build advanced applications.
It is important to be sure that with this metaphor, you clearly explain the difference between the APIs and the underlying service.
The API is the way to access and interact with the service, and the service is the technological brick that makes it valuable.
APis are important because they expose the capability brick to be integrated with others with a formalized interface.
With Lego Bricks, it is easy for everybody to understand its shape, and it is easy to connect to another. With APIs, it must be easy to understand what capabilities they provide, and make them easy to connect with others.
An important point too, is that in a large organization, like a big box of lego bricks, not everybody will use building brick to achieve the same structures. LEGO’s own advertisement represents the idea really well.
While you craft well defined and purposeful building bricks, other teams and partners will use the brick in the representation they see of the capability, like the shadow below each picture. This is what drives children’s imagination and organisational innovation: the original purpose of your brick resonates differently with another person’s need or interpretation.
It talks also to IT managers about the fact that an old brick can be replaced by a new brick, but if the interface is the same, you respect the original contract and without breaking applications. Over time as your capability builds, resilience, security and scalability can be built into each [new? upgraded?] brick reducing downstream dependencies and being able to respond better to unplanned events.
For Executives Sponsors and C-levels
→ Biology : biological cell and macro ecosystems
From a biological cell to any living ecosystem, biology describes their need to be closed enough to survive and be protected from the danger of the environment; while being open enough to evolve and exchange with its ecosystem and to be able to adapt to change.
It is the same for companies. They need to protect their assets enough to stay ahead of their competition, but in a connected world, they need to be open enough to scale partnerships and business development. Especially as more and more corporate capabilities are delivered via IT, then the need grows to be more open and more collaborative, while being more secure. This is where APIs come into action, as they will define what the organisation exposes internally to other parts of the organization, and what they expose to the world.
Biological cells have a porous membrane, that let things come in and enable things to go out. If a biological cell lets too many things go in, it faces danger of contamination and infection. If the cell is too open, it dilutes itself in the environment and dies. So any living organism, like any digital organization needs to manage this openness. This can be achieved by the design of APIs that the organization exposes internally and externally.
Another way to see the metaphor is about living ecosystems, and the fact that organisms grow differently depending on the interactions they have with their ecosystem. 
For example, in remote ecosystems like islands, animals can evolve getting smaller over time (Insural dwarfism) because they lack a diversity of interactions as on mainland. It’s not that they don’t have the same competition, but they cannot access the same quantity of resources that would make them as big as they could be.
Organizations that don’t understand that their IT needs to be open and collaborative will never achieve their full potential, because of corporate technology insular dwarfism. APIs can help these organizations internally by exposing capabilities of special teams to be used by other in the organizations (without consuming valuable resources rebuilding existing software) and can also become platforms exchanging data and capabilities with the whole business ecosystem, to scale business and reach customers.
Conclusion :
Of course these 3 metaphors are not perfect, like all metaphors, but they can help to start the discussion about the need for the organization to start adopting APIs, on the business side or the IT side. Let’s engage on twitter @medjawii or reply in comment if you have good metaphors you use on your own.
