APIs for non-techies (like myself)
“Thanks for explaining APIs in terms I could actually understand.” This sentence was used by one of the many visitors I was talking to at our Mindtrek 2017 stand. APIs are key building blocks in service digitalization, integration, smart cities and IoT. Therefore, an increasing number of non-developers or non-techies need to understand at least in high-level what are you talking about, when you are talking about APIs.
I’m a non-technical person myself. Nowadays, way less non-technical than I used to be when I first joined an IT company some 18 years ago. I have a background in Translation Studies, which means that many of the technical concepts I have needed to understand at high-level have been explained to me as approachable analogies.
Later, I have applied the same techniques when I’m explaining APIs, API economy or API management to directors, mayors, engineers outside IT or product managers. I have even used buckets (actual buckets) to explain APIs and API management.
So here goes… To all of you, who have heard that your company or organization would need to include APIs in your strategy or that your integrations should be based on APIs. And all you have at hand is a technical definition of an API that makes no sense to you.
Let’s concentrate on two types of APIs: REST APIs and real-time APIs. If you do a search on the abbreviation API, you will learn that it stands for an Application Programming Interface. Ok. Sounds like a nasty technical word, something you would expect your SW architect to understand.
There was a brilliant Tweet already from 2013 that uses a restaurant as an analogy to explain APIs. If you go to a restaurant as a customer, you are not allowed to enter the kitchen. You need to know what is available. For that you have the menu. After looking at the menu, you make an order to a waiter, who passes it to the kitchen and who will then deliver what you have asked for. The waiter can only deliver what the kitchen can provide.
How does that relate to an API? The waiter is the API. You are someone who is asking for service. In other words, you are an API customer or consumer. The menu is the documentation which explains what you can ask for from the API. The kitchen is for example a server, a database that holds only certain type of data — whatever the buyer has bought for the restaurant as ingredients and what the chef has decided they will offer and what the cooks know how to prepare.
Alternatively, you could think of a shoe shop, the kind that only has one size per model at display. You need to ask the salesperson to get your size. The salesperson can go to the backroom to check, whether they have the right size and color available. The customer is not allowed in the storage room.
So you need to approach the salesperson and make a request for the required model, size and color. The salesperson will either bring the required shoe pair or tell you it is not available. This is what APIs do as well: if what you are requesting is not available, the API will return an error: “Resource is not found.”
Our Chief Apitalist Jarkko Moilanen has also explained APIs as bridges. There is river and roads on both sides of the river. For the cars to go to the other side of the river, you need a bridge. If you have a bridge, you may need to control the amount of traffic: you only let a certain amount of cars pass in an hour. Since it can be fairly expensive to build the bridge, you may also want to collect some toll for using the bridge. This is true for APIs as well: you need to control the data traffic in order for you server not to get jammed. You also may want to monetize the traffic to your APIs.
What I have explained above, are metaphors for REST APIs. REST APIs are digital middlemen who handle requests and responses. They allow others to use your resources and services, without allowing them access to your backend, for example your database. And the APIs can only deliver what they have available. And just like when interacting with people you need to use magic words, like please, when interacting with APIs you need to know how to use magic words like GET.
Real-time APIs are a slightly different story. They do not rely on request-response pattern. Instead you could think of a newsletter. Let’s say a company is publishing in an interesting newsletter. You decide to start subscribing to it and one way or another notify the publisher about your subscription. After subscribing, you keep getting the newsletter, unless you unsubsribe. The real-time APIs publish data more frequently, way more frequently, but the principle is the same. They are simple messages coming from devices. The messages are then published to the API consumers, who have subscribed to them.
IoT (Internet of Things) will make the real-time APIs more and more important. A typical example of real-time APIs are bus or tram locations. Vehicles have small devices that are frequently sending the vehicle location at a particular point of time. The locations are then further published to the API consumers, e.g. applications that show the vehicle locations on maps.
So why should a non-techie care? APIs are becoming products. With products you need a vast array of skills, including product management skills. And that is a different skill set from development. APIs may also need to be designed by non-developers. Or as a minimum, the design may need to be commented by the non-techies. We will come to a point when APIs also need to be consumed and developed by non-technical people. Tool wise we are not there yet.
To learn more, join the APIOps community. For more commercially oriented needs, contact us.
