We all are confronted with the situation in which we have to explain what API is to non-technical people. You can of course jump into technical approach but that in my experience leads to rolling eyes. That is because you will most likely use acronyms they have never heard of. Treating APIs as products also means you will include at least marketing and business layer in the team. They need to understand what API is and even the difference between API types.

Let’s use power and consuming power as an example here. At least let’s start from simple things. The analogy is not perfectbut should help you marketing and business to understand what APIs are and how platforms and API management connect to the game.

Plug-n-play

Previously some people said that you can make an analogy between powerplug on the wall and API. With traditional REST API I was against it, although yes you could say so. Just plug it in and that’s it. As a consumer you don’t need to worry what happens behind the plug - it just works…if it does. This the idea of and API as well. You as a consumer do not need to know the complexity of operation behind the socket. There’s also little you can do if the socket does not provide electricity. That’s not in your hands.

In pure REST consumer is the active part not only in connecting to “powersocket” but also in consumption. That is not the case with powersocket. You just plug the cord and electricity starts to flow. This is were you can inject business in the picture and onboard your sales people and business developers.

When you want to get electricity from the socket, what do you do? Do you buy each time separately some amount on watts? No, you make an agreement with the provider and pay as you go. You pay for the electricity you consume. You don’t need to know how much it is going to be today or tomorrow. Of course electricity might be bundled to for example the rent. Then you have subscription model and you pay fixed amount each month. Voila! Now you have added business thinking to the analogy as well.

In electricity there’s a valuchain behing the scenes. You are the consumer, you landlord has been wise enough to build power sockets to the wall around the house. You have made and agreement with the electric company. Some other organisation most likely has build the wires to transport electricity and at the end there’s a powerplant.

You can switch the electricity provider, but thanks to standardisation you don’t need to change the API (socket on the wall). With APIs this is not the case in 90% of the cases. Every provider provides unique API. This is one spot where the analogy falls apart. But let’s not be too picky.

What about integrations?

You might be asked at this point “What about integration? How is that related to the picture?”. In this case the integration would be that you would have just the raw cords sticking out from the wall. You would most likely have three cords: positive, negative and ground (might be missing occasionally). You would need to peal your cords and connect each cord. Lucky for you someone has taken care of that for you and you have easy to use cords with plugs “integrated” already and that plug is compatible with the socket on the wall.

What if the wall contains multiple sockets?

And if you have multiple power sockets or better yet combination of power, tv antenna and radio sockets, phone landline next to each other? This gets a little complicated now. That’s a API family. Each socket is build for a purpose. Power socket for electricity (although nowadays you can use those for LAN purposes as well), tv antenna feed to see television stream and radio socket to hear your favourite radio station dj playing same old songs every day.

What about platforms?

In here you API might be one of the sockets only. Then the framework which offers all the sockets is a platform. It is not created by you, but someone else. You provide the feed to the socket. Platform provider might provide different kind of layouts for the framework, your offering included or not. An example of this would be F-Secure Security Cloud API for URLs which is provided at AWS marketplace.

That product (API driven service) is owned by F-Secure, but it is easy to take into use as part of the AWS “framework”. It happens just by doing some clicks. Just like plugin the power cord to the socket on the wall.

What about internal APIs?

If your IT people are wise, they have API management which includes the internal APIs as well. That API management is the above mutlisocket framework. It provides capabilities (authentication, products catalog, accounting etc) and your own applications connect to each of them so solve some kind of problem in the application level.

Then the partner APIs?

Some wiseguys in the audience might raise up the question of partner APIs. They heard about it in conference or read the story of Kesko plugin to Chinese marketplace with Partner API.

In the above next to your Products API is the partner focused version of the Product API. There might be even a third Product API which is open to all 3rd party developers.

Try other analogies

I’ve used couple of other analogies in the past. A friend of mine asked how to explain API to a 6 year-old. I’m a happy father of four kids (family contains in total 7 kids though). My suggestion was to use father as a API. The kid asks for breakfast. He “orders” bread for breakfast. Then the “daddy” acts as API between the ingredients and the kid. Kid keeps on making requests like “I want to cheese on it too!”. Daddy replies “200 OK” and does the job. Eventually daddy takes the sandwich to the table for the kid. The thing is that you have to get on the same level with the audience. Understand their limitations and abilities. They have strengths but those might not be in the technical solutions like API. Their task is not to understand the technology, they need to understand the concept.

Another analogy idea which I stole from the web somewhere is restaurant related. The waiter is your API. The menu is API documentation. The chef in the kitchen is intergration. Ingredients are the bits and bytes often referred as data or functions.

Some more to read from 100 Days DX