“Calling the API” is a common phrase you’ll hear developers using. It’s actually a pretty simple concept, though of course the details can get complicated if you dig in a bit.
The short version:
An API (that’s Application Programming Interface) is a way for one piece of software to call another and request that an action be performed, or that data be returned, without having to know how this request is carried out.
At a high level, an API is like ordering from a menu at a restaurant. The menu lists everything you can order. You pick what you want, making any choices allowed by the menu (salad or fries with that?). The order goes to the back of the house, where magic happens, and then you get back your meal without knowing what’s going on back there (which is sometimes a really good thing…)
To take this analogy even further, this is a restaurant run by an egomaniac chef who refuses to accept any substitutions not explicitly listed, and will throw you out if you try to order anything not on the menu.
In Real Life
OK, analogies only get you so far.
In real life, modern software is made up of many different modules, that all do different things. So you’ll have a graphics module that will draw charts if you pass it numbers, a search module that will search a database for whatever information you ask of it, another that will throw up one of those CAPCHAs that ask you to “find all the pictures with fire hydrants”, and so on.
If a developer had to write all those features from scratch every time we’d never get anywhere.
So a lot of modern software development is about choosing the right libraries of functions and then stitching them together to create a new application made up of these different Frankenstein’s monster parts.
Ahem.
OK, it’s not that bad.
How to make these pieces work and play nice with each other is where APIs come in. An API allows a software function to put out a simple face to the world that acts like a menu – “here are the things I can do, and here’s how to ask me.”
Let’s consider a simple example where you want to fetch weather information for a specific city using a weather API.
Here’s a somewhat-real-code example demonstrating how to call the OpenWeatherMap API to get the current weather for New York. This code is in a language called Python.
The first thing we do is load a pre-written library of code that knows how to send requests over the internet. This library is (very originally) called “requests”. More on this later …
import requests
Now, we’re going to put together the actual request we want to send. We stick together two parts, the url (the internet address) to send to, and a parameter to send there (in this case, the name of the city):
Now we’re actually going to “Call the API”.
We do this by sending this request over the internet using the “requests” library, and then we’ll store the response.
response = requests.get(request_url) temperature = response['temp'] weather_description = response['weather description']
What that code does is send the “New York” string of text to the address “http://api.openweathermap.org/data/2.5/weather”. That’s “calling the API”.
(That API address is sometimes called an “endpoint”).
We capture the response we get back, and interrogate it, pulling out the temperature piece and the description.
Then, for good measure, let’s print it out:
printf('The temperature in New York is {temperature} and the weather is {weather_description}.')In real life there would be another step to convert the response into something called a JSON file, and it would need all sorts of checks for errors and so on. But the basic pattern is how all APIs are called: construct the request, send it, and process the response.
One huge advantage of this modular approach is a developer can rapidly build new software from “building blocks” without having to know how they work in detail. They only need to know how to call the API – i.e. know what the limited number of options are that they can send to the software.
Change is Good
Another big but often less-discussed feature of this approach is it makes change simpler.
Assume that sending that string above to the API is guaranteed to return weather data in the same format (essentially it’s a contract). The software at the other end can change completely on the inside and it won’t matter – we only see that the data coming back looks the same as before.
That makes changing and testing software much simpler. Imagine if every time that weather software changed they had to let everyone in the world know to update their own code.
Internal APIs vs External APIs
OK, let’s go a little deeper.
In the example above, we are actually using two APIs, one internal, one external.
The first line (“import”) pulls a library of code called “requests” into the code we are writing. Then we call a function requests.get(“<url>”) that will do something to send that request to the Weather API that is run by some remote, external service.
Under the covers, that “requests” library is doing a lot of thankless tasks. It establishes that we have an internet connection. It translates the url into an actual internet address. It communicates with the service, deals with communication errors, and finally packages the reply up for us.
That function call “requests.get” is actually an example of calling an internal API – we know we give it a url, and we know we get a response back, but we don’t need to know the details of how it’s working.
We are then using that to call an external API hosted on the weather site.
Both approaches provide the same benefits – we can glue together components of code that do specific things to build new services.
Types of APIs
There are multiple standards for how an API is constructed, and of course, these evolve over time.
Most of the time you won’t need to know any of the following terms, but you’ll look like like a boss if know what a “RESTful” API is, so let’s talk about that one.
REST (Representational State Transfer) is a popular style for designing networked applications. It involves an internet-style URL as the API address, and passes parameters to that address in a standard format.
(The internet weather API example above is a RESTful API).
The key thing to be aware of about this style of API is that is is “stateless” – that is, every call passes everything needed for that specific operation. The remote system doesn’t “remember” anything the next time you make a call.
Why is that a good thing?
Well, one thing about networks is … they go down and you lose your connection. Reconnecting and re-establishing “hey, where were we again?” is complicated, so this approach is designed to work when keeping a connection open is not guaranteed. (One implication of this is that if authentication is required, it has to happen with each call).
For Extra Points: a RESTful API is a popular type of stateless API. The opposite is called stateful, meaning a system that remembers the state it was in from previous actions.
You may also hear OData (Open Data Protocol) mentioned, which is an open standard for building and consuming “RESTful” APIs, as well as perform advanced queries and filtering of data
Here’s a few others you may hear, just for completeness. You will probably never need to remember these:
- GraphQL: Developed by Facebook, GraphQL is a query language and runtime for APIs. It enables clients to request exactly the data they need and nothing more, reducing the amount of data transferred over the network
- SOAP (Simple Object Access Protocol): SOAP is an older protocol that is still used in certain legacy systems and enterprise environments
- gRPC (gRPC Remote Procedure Calls): Developed by Google, gRPC is a modern, high-performance framework for efficient communication between microservices (literally, very small pieces of software that do one thing)
- JSON-RPC and XML-RPC: These are remote procedure call (RPC) protocols that allow clients to call methods on a remote server as if they were local. These protocols are simpler than REST or SOAP but have less built-in functionality
Take Aways
All right, that was the quick rundown on APIs! Here’s a quick recap:
- APIs provide a way for software developers to use libraries of software that provide specialized services without having to know the details of how it’s done
- Internal changes to software are “hidden” behind the API, meaning that users of the API don’t have to make changes every time the software is updated
- There are many standards for how to build APIs, but all follow the same pattern: package a request, send it to the API, unpack the response.