home articles newsletter

What is an API?

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

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 share 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:

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:

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:

👉 In an open environment:

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:

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

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 to using the service:

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

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 consume the API within the pre-defined conditions, it’s 👌.

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