The 7 Most Commons Myths About APIs
“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 coined was in 1968. In the last 30 years, the service interface concept have been tightly coupled with vendors and software products (eg. SOA, ESB, Webmethods, SOAP/XML Webservices). To detach the service interface concept to these out fashioned products that did not deliver their promises, the industry pushed the word “API” as the new concept to enable the transition to a new set of technologies and products (REST, JSON, API gateways, API management, OpenAPISpec, GraphQL etc)
Service interfaces are APIs, because 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 state that 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 reinforce the idea that APIs are not just a technical topic.
“APIs must be handled by our 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 as only 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 transformation involved often an API-Center of Enablement group, that mixes IT departments but also business stakeholders, and sometimes Sales and HR!
“APIs must expose the data or the service as it is in my 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 ad 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 expose 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 other .
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 examples, 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 policies, just sticking and scaling to their existing business model
In another article, I will aboard other ones 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”