API 101: What even is an API?

Johanne Andersen
Aug 18 · 3 min read
Sending a request to an API

API’s are all over the place, but what are they actually? How do you create one? What are the best practices?

I’ll try to shed some light on these things over the next couple of months with this series on API’s. First off, let’s get the basics out of the way.

Simply said, an API is an interface between a client and a server. The client sends requests for data to a server. Behind the scenes, the server fetches the requested information and responds.

The data can come from all sorts of places. It could be a database, a file or even another API.

So an API is what allows a client to interact with a server. The client can be anything. An android app, a website, a desktop application or a command-line program.

This is one of the reasons why API’s are so useful. When you implement the API you have to specify the contract (the structure of the responses and the requests), and as long as you adhere to this contract, it doesn’t matter who is going to use your API.

Which means you might have a web UI that interacts with the API, but nothing is stopping you from implementing an app later. Your backend won’t have to change at all.

Another powerful aspect of API’s is the fact that the client doesn’t care about the implementation of the server. The contract is king. How the server gathers and stores the data specified by the contract is entirely up to the implementers of the backend.

A client sends a request to a waiting server
The server fetches the data
The server responds with the data according to the contract specified by the API

Making it more concrete

Let’s take a concrete example of the classic to-do list. Say we want to build an API for a to-do list service. Which means we need to specify the contract.

First, we need to tell the client how to query the API for a specific resource. Here a resource is a representation of specific data. In our case, a to-do list could be a resource.

The request could look like this:

GET https://todo.johanneandersen.me/todolist

Here the GET specifies what kind of HTTP request to send. More on this later. The /todolist specifies the resource we want data for.

Then we need to specify what you should expect to get as a response, which could look like this:

{
"id": integer,
"items": [
{
"id": integer,
"title": string,
"created_datetime": dd-MM-YYYYT00:00:00,
"completed": boolean,
"completed_datetime": dd-MM-YYYYT00:00:00
}
]
}

So as a programmer who wants to query the API, you know exactly what to expect when you send a GET request to https://todo.johanneandersen.me/todolist

This is just scratching the surface though and over the next posts, I’ll be diving into what a REST API is and how to design one. We will also look at authentication, authorization, and pagination. Along the way, we will build our to-do list API as we explore these topics. As a bonus, I’ll also be looking into GraphQL and tips and tricks for Postman.

Thank you for reading, see you next time!

Next post → API 101: Designing kick-ass REST APIs

Data Driven Investor

from confusion to clarity, not insanity

Johanne Andersen

Written by

Software Developer, learning enthusiast (obsessor…) and lover of sleep. Basically, a recent CS grad trying to adult.

Data Driven Investor

from confusion to clarity, not insanity

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade