Rémi Mercier

Posted on May 23, 2019 • Originally published at remimercier.com

What is an API?

#api #beginners #explainlikeimfive

Feeling queasy about explaining APIs to your grandma 👵 or a non-technical client 👔? Lemme help you out!

Before we start, I’d like to ask you a few questions. Do you know how:

Authentic Weather knows the weather it’ll be doing during your upcoming trip to Dunkirk?
Trainline knows if a seat is available (of that very same upcoming trip to Dunkirk)?
Airbnb puts available flats on a map (do I even need to say “of Dunkirk”)?

These past few years, APIs (also known as Application Programming Interfaces) have spread like wildfire in the startup growth game.

To quote Paul Bonaud, back-end engineer at @trainline_fr (formerly Captain-Train):

APIs, quite an interesting and vast subject, isn’t it?

Wrapping your head around APIs can be challenging for non-technical users. What’s an API? What can be shared through an API? Data? Services? How does one design an API? How do you code an API?

Because I asked myself all of these questions (and many more), I’ve decided that it was time to get a better understanding of what APIs are all about. It’s a bit scary though - especially when you come from a non-technical background - but I’m sure people will find it entertaining. I plan on writing about various topics:

what’s an API?
how does it work?
who’s using it?
etc…

But let’s start from the beginning.

What is an API?

APIs - or Application Programming Interfaces - are defined as a set of functions (a coded procedure performing a particular task) through which two software can talk to each other without any human intermediation. An API is an abstracted point of entry to a piece of software with a description of the open interface and its behavior.

Let’s break that acronym down:

Application: By application, we mean a service with which a developer wants to interact. This service can be a stream of meteorological data, an image sharing app or an open data portal.
Interface: The interface is the entry door to the service. You have to go through that door to interact with the service capabilities (e.g., filtering meteorological data for a city, publishing pictures on Instagram…)
Program: The program is a set of coded procedures written by a developer. The program is designed to interact with the application, so we don’t have to. For example, the program can submit a postal address to get coordinates (think Airbnb or Google Map).

To sum it up: APIs are programs using a specific point of entry (the interface, also call an end-point) to interact with an application (or some features within this application).

Ok, but what does an API do?

Nowadays, APIs are well covered. You’ll find lots of articles about the “Greatest XXX APIs every developer need to know.” But the very basics of APIs are not concisely explained and still elude non-technical users.

An API allows a developer to access a service. One usually says that an API exposes a service.

We’ve seen it above; the service can come in many shapes and forms: real-time data streams (e.g., Twitter), maps (OpenStreetMap), publishing a picture (Instagram).

Developers write programs that consume these APIs.

APIs can be used in various environments:

👉 In a closed environment:

to mutualize your company data across departments’ lines
to expose a database’s serialization made from multiple data sources
to test an API in a secure environment before releasing it publicly

👉 In an open environment:

expose data to the world: think open data portals
allow other companies to offer their services within your application: think Giphy integration in Slack, Zapier…

Let's try a metaphor

Metaphors can be tricky when it comes to technological matters. But the gist of APIs can easily be understood using the electricity network as a proxy.

Let’s start with an electricity supplier:

this supplier produces and distributes a service: electricity
to distribute this service, the supplier relies on infrastructure: the electric network (stations, transmission lines, utility poles, sockets)

Now, let’s take a lamp that needs to consume electricity:

for the lamp to work, it needs to be connected to the electric grid
to be connected, the lamp is sold with a plug that fits standards sockets

The socket is a standardized point of entry (an interface) through which a lamp consumes electricity. An API is a standardized point of entry (an interface) through which a program consumes an application.

APIs allow developers to delegate a service they need to consume. In the same way, the lamp’s owner delegates the electricity needed by her lamp to the electricity supplier.

Let’s dig further. APIs and electrical sockets both specify how the user can consume the service. Remember our lamp? It needs to respect some conditions for using the service:

the number and shape of the pins
voltage and frequency
type of current
etc…

APIs will do the same and specify conditions to use them:

number of API calls for a defined lap of time
what you can expect to do: read and/or write
etc…

Thanks to the standardization of sockets, you can plug several lamps in your home without thinking twice about it. What matters is that every socket is functionally similar: it brings electricity right into your home.

APIs and sockets are abstractions for the service they expose.

Wait, what? Abstractions? 🤔

They hide the nitty-gritty of the service the customer uses.

Without sockets, you’d need to twist your lamp’s wires around those sticking out of your wall. Lamps don’t give a dime about the details of the electrical grid. They work whether the electricity comes from solar panels or wind turbines; whether the cables within the wall are black, red or pink; whether other lamps are plugged into the network or not. As long as the electricity supplier provides the lamp with its functional needs (AC and 110 volts if you live in the US), the supplier can modify its network at will. Without this abstraction, you’d need to wrap your lamp’s wires around the wires in the wall.

The abstraction works the other way round. The electric grid doesn’t care about the design of your lamp. Whether your lamp is designed by Ikea or Wilhelm Wagenfeld, the grid only cares about the plug fitting the socket. Electricity flows from the station to your socket even if no lamps are plugged in it.

APIs work the same way.

Without APIs, Authentic Weather would need to weather.com’s data on a regular basis (or any other meteorological data provider). Thanks to APIs, Authentic Weather doesn’t care about the nitty-gritty of the meteorological data it receives every second. As long as the data stream (accessible through the API) is functionally stable, Authentic Weather is happy (and its users are happy).

The abstraction works the other way round. weather.com’s API doesn’t care about your app’s color scheme. As long as your app consumes the API within the pre-defined conditions, it’s 👌.

Was this helpful? Lemme know in the comments or on Twitter!

Top comments (22)

Jean-Michel Plourde • May 23 '19 • Edited

What a great post Rémi!

I always kind of knew the role of an API but didn't grasp the concept enough to explain it in simple terms. You did it brilliantly. I really liked the lamp metaphor. It goes straight into my mental models.

Rémi Mercier • May 23 '19

Thank you Jim for the kind words!

Jean-Michel Plourde • May 23 '19 • Edited

Just to add a bit more as a good to know: Your electricity provider do care about the design of your lamp. If your lamp returns current to the grid (I will spare you the wave-function math behind) it damages it. Electricity providers use Fourier transforms to evaluate how much your appliance is damaging the network and they charge you money accordingly. Fortunately, this problem mostly concern the industry field.

Rémi Mercier • May 23 '19

That's interesting! Didn't know 1) electricity went back to the grid 2) that it harmed the grid 3) that providers were charging you for it. There's a lil' something to learn every day on dev.to. 🥳

I'll dig on Fourier too. I've its transforms but it's remote from my usual interests so it's kinda hard to grasp at first (so I guess I won't write an article on the subject anytime soon! 😄)

Max Ong Zong Bao • May 24 '19 • Edited

Awesome article on the part of standardisation.

I think it should be more of in the form of contract(API documentation).

Which both parties has to agree upon to use the API.

Therefore if either parties breaches the contract.

The repercussion is it won't work or behave abnormally with a valid reason by either parties on why the contact is breached.

No one will enter a contract if it is not favorable for both parties to be in a partnership to work together.

Rémi Mercier • May 24 '19

Yes, the contract was (and still is tbh) an API concept I found difficult to understand. May be because a lot of public APIs have a very loose understanding of contract breach (ie no backward compatibility). But again, not-so-well-known APIs upon which a lot of hardware is built fell into the contract category.

Your explanation is 👌 Max and made it much more graspable to me.

Max Ong Zong Bao • May 24 '19

Actually, it took me a while in working with a frontend developer that made me realise the importance of it.

I found out later that either you create your own contract by yourself or you could use existing template contract like OpenAPI Specification to facilitate and make your life easier for API development.

Rémi Mercier • May 24 '19

Yes yes, Swagger is awesome. I've only beginning to use APIs that use Swagger, and it's neat.

Didn't realize it was a contract, though 😅. But now that you pointed it out, this seems obvious!

Max Ong Zong Bao • May 24 '19 • Edited

Hahaha check out Postman, It's a godsend and allows you to import OpenAPI files into Postman to make your life in creating APIs easier.

I believe the new release of Postman allows you to create your OpenAPI specs as well.

Joshua Kahn • May 24 '19

Great piece Remi. A friend of mine produced this video when we were on Best Buy's Open API team years ago. The idea was to produce a really simple and effective explanation of the attributes of open api's that make them so powerful. There's a little bit of the 'lies told to children' thing happening, but if you need to actually explain API's to your grandma, it's pretty great.

Check it out: youtube.com/watch?v=7r7QpIDEI_o

Rémi Mercier • May 24 '19

Will check it out! Thanks for sharing Joshua!

Liyas Thomas • Nov 28 '20

Great post. Feel free to use open source API testing tool: Hoppscotch to spin up these APIs on-the-go directly from your browser window and get to know about how APIs behave when requested at client side.