We were discussing APIs in the office the other day, more specifically, how do you describe an API to someone less technical?

My favourite answer was 'magic pipe' but that doesnt really help explain whats happening.

eli5

An API is a set of rules that a company publishes that says: if you ask our computers in the right way, they will do something and send you the result.

an API is really a collection of a few concepts that we can explain when we break them down.

I’ll try and explain the following concepts: API specification, endpoints, protocol and error handling

Bear with me whilst i torture a metaphor to explain

Imagine for our purposes that you are a customer going to a restaurant. now this is a special restaurant, it has three kitchens and you can ask the chefs to prepare meals on the menu with ingredients that you give them

Specification

The restaurant has a set number of meals that it can do, and they publish their menu for all to see. The menu is their API specification.

Endpoints

There are three separate kitchens in this restaurant, one that does breakfast, one lunch and one supper. You tell the waitress to which kitchen to take the order. these kitchens are the API endpoints.

/breakfast
/lunch
/supper

Protocol

There are a couple of different ways that you can give your instructions to the waitress, you can either say ‘i’d like the full english’ which is the equivalent of a GET request. Anyone else in the restaurant can hear your order when you order this way, so be careful what you ask for if you don’t want anyone to know what you order. Asking for soup from the lunch kitchen would look like this

GET /lunch/soup

You can also put the ingredients in a big envelope and write a note in there with your menu choice and then seal the envelope before giving it to the waitress so she and the other customers never see what you want. this is a POST request. Asking for a ploughman’s sandwich from the lunch kitchen would look like this

POST /lunch {ingredients: [bread, cheese, branston pickle], meal: ploughman’s sandwich}

The waitress heads straight to the right kitchen and gives your order to the chef. think of the waitress as the physical structure of the internet, she just takes your order to where you tell her to go.

When the waitress gets to the kitchen, the chef will look at your order and then try to prepare your meal. The Chefs here would be like the DataSine algorithms processing an image and then responding with their analysis.

If the chefs can prepare the meal you want, then they will do that and send your meal straight back as quick as they can


Error Handling

Chefs however are a picky bunch, if you asked the breakfast kitchen for boiled eggs but sent pomegranates, they will send the waitress back with a message to tell you why they can’t prepare your meal. Here they’d send a 400 error.

If you had an old copy of the menu and asked the supper kitchen for fondue, but they no longer make fondue (they stopped making that in the 80s) they’d send you a 300 error to say that no longer exists

Sometimes you’ll send the right ingredients and the right instructions to the right kitchen, but the chefs are all too busy or have forgotten how to cook and can’t prepare any meals right now. They will send you a 500 error when this happens.

Other times they will be special chefs that only certain people can use, and you can only ask them to prepare your food if you tell them that ‘Tim sent me’. If you don’t tell them this, they’ll send back a 401 error.

Real Life

Every website you visit is accessed over the most common web API. Typing a web address into your browser is a GET request, every web address is an api endpoint, and I’m sure you’ve all seen the dreaded 404 “page not found” error.