DEV Community

Cover image for What is an API?
Rémi Mercier
Rémi Mercier

Posted on • Originally published at

What is an API?

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”)?

man's brain exploding

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).

api diagram

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’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.’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)

j_mplourde profile image
Jean-Michel Plourde • 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.

mercier_remi profile image
Rémi Mercier

Thank you Jim for the kind words!

j_mplourde profile image
Jean-Michel Plourde • 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.

Thread Thread
mercier_remi profile image
Rémi Mercier

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 🥳

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! 😄)

steelwolf180 profile image
Max Ong Zong Bao • 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.

mercier_remi profile image
Rémi Mercier

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.

steelwolf180 profile image
Max Ong Zong Bao

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.

Thread Thread
mercier_remi profile image
Rémi Mercier

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!

Thread Thread
steelwolf180 profile image
Max Ong Zong Bao • 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.

joshuakahn profile image
Joshua Kahn

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:

mercier_remi profile image
Rémi Mercier

Will check it out! Thanks for sharing Joshua!

liyasthomas profile image
Liyas Thomas

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.

GitHub logo hoppscotch / hoppscotch

👽 A free, fast and beautiful API request builder used by 100k+ developers.

thefoxboxman profile image
John De Costa

Great work Remi. Excellent metaphor. Keep up the brilliant writing, love your style

mercier_remi profile image
Rémi Mercier

Thank you John for the kind words!

carlosalfarodev profile image
Carlos Alfaro

Nice way to explain API's! Thank you!

tmpou1 profile image
Thomas P

Good job Rémi 🚃 !

mercier_remi profile image
Rémi Mercier

Thanks Tom! 😉

node_srojas1 profile image
saul rojas

Thank you for the information, and the great metaphor 🤙

banzyme2 profile image


angelarae63 profile image
Angela Whisnant

Perfect! Thank you!

Some comments may only be visible to logged-in visitors. Sign in to view all comments.