The 7 most commons myths about APIs

Over the last 10 years, I'v e heard many misconceptions about APIs that are still here in 2020, and in this article, I will try to tackle the most sticky ones.

“APIs are a new technology”

APIs as Application Programming Interfaces have been around since the advent of software, but the first time the term was officially coined was in 1968. But from the 1990's and the era of Services and SOA, the service interface concept has been tightly coupled with vendors and software products (eg. ESB, Webmethods, SOAP/XML Webservices, CORBA). As this set of technology did not deliver its promises, in the 2000's, the industry pushed the word “API” as the new concept to enable the transition to a new set of technologies and products and detach the service interface concept from their out of fashioned products.

APIs are not binded to any technology. Would you say that HMI (Human Machine Interface) is a technology or is a design practice that involves technologies that can change over time? APIs are these Software to Software Interfaces.

“APIs are a technical topic”

Originally yes, but in a world where IT capabilities are a competitive advantage, APIs are also a business topic. Especially when you consider Conway’s law, that statesthat organizations who design communication systems are condemned to reproduce their organization's structure inside their communication systems. APIs are a way to expose capabilities as products and liberate interactions in the organizations, making them discoverable, autonomously integrable by others and managed like products. In that sense, APIs are an IT term, with business implications and must be considered now not only like a technical topic. The APIs-as-product concept reinforces the idea that APIs are not just a technical topic.

“APIs must be handled by the IT department”

Because of their ability to re-align business with IT, exposing capabilities as products, IT department is not designed to handle alone all the aspects of API-led transformation. Most of the time, when IT is the only one involved in APIs, APIs are designed more towards integration and technical interoperability between internal services instead of focusing on exposing capabilities towards business departments. This is why most of company-wide API-led transformations involved often an API-Center of Enablement group, that mixes IT departments stakeholders but also business stakeholders, and sometimes Sales, compliance and HR!

“APIs must expose the data or the service as it is in the system”

The main interest of designing APIs is the ability to use the interface representation to expose only what needs to be exposed, and in the way that will help and inspire future implementers to understand the underlying capabilities in his context.This is why we often consider APIs as much exposing interfaces ads hiding interfaces.

Your interface is not your data model or object model. A restaurant menu is not the floorplan of the kitchen and is not the list of ingredients in the fridge! It exposes what can be ordered and hide what the kitchen can probably do but that the Chef don’t want you to know. 

“There a 1to1 relationship between APIs and services”

When most of the time it is designed that way, there is not a necessary a 1 to 1 relationship between services and APIs. 1 APIs can be the interface to access one or multiple service capabilities and 1 service can have multiple APIs depending on its interactions with others. .Example : 1 API for exposing a Banking scoring capability that call behind the scene 3 different services for current scoring, probability of default in the next 3 months and country risk. It is like a restaurant that would provide 1 menu with food and drinks to customers to make things simple to order, but behind the scene would have an independant kitchen and a bar, that have 2 different P&L. 1 interface, 2 independent services.

On the other side, a Hotel database that expose 1 REST/JSON API to other travel platforms which work with this set of technologies, and expose 1 SOAP/XML API for the Airline ticketing industry that still works in majority with this set of technology. It is like a restaurant that for the same kitchen and food production capabilities design 1 menu for adults and 1 menu for kids. 2 interfaces, 1 service.

So when simplicity or business needs requires it, you can overcome the 1to1 relationship between APIs and Services.

“API Management is about API gateways and security”

API management is the practice to align API enablement and consumption with business priorities, inside or outside the organization, while securing and monitoring traffic and threats. It involves API gateways but also Analytics, Traffic Monitoring, User role management, Developer portals, and more and more features on the API lifecycle management like API design, API documentation, API testing and API Versioning. The end-goal of API management is to align APIs with Business KPIs.

“APIs need a business model”

Not all APIs are made to be exposed outside the organization, and when they are, lots of people consider that they must be monetized and thought with a dedicated business model in mind. Unless your main company product is an API, for organizations which have already a business model, you should not think in terms of what is the best business model for your APIs, but what are the best APIs for my business model. For example, Insurers may want to open API for free to create an ecosystem of applications for their customer and become a platform, to at the end create more customer acquisition and retention on sold policies, just sticking and scaling their existing business model, and not inventing new ones for their APIs.

In another article, I will aboard other myths for more technical people like 

“Microservices don’t need APIs”

“Designing an API is to write its Open API specification”

“Documenting an API is to provide a good API reference”

“Developers portals are for external developers only”

“Developer portals are the only way to expose APIs for discoverability”

" API keys and OAuth are authentications method for APIs"

And you, what are the main myths about APIs you hear everyday?

If you are interested , I've designed a specific 1-day training about breaking all these myths and the one your IT teams and Business teams may still have on APIs. You can reach me on [email protected] if you want to settle one for your organization.