If you’ve had anything to do with the tech industry, API is probably a term that you’ve heard. This is understandable, APIs are an integral component of many modern computer applications. In this post, we will be looking at APIs and supporting our understanding with an example of how APIs could be applied.

But What Are They?

Let’s start off simply: APIs are mediums through which computer applications share data. These are interfaces that an application will use to talk to the other. A client can request some data from an API which will execute some code and then send back a response. When a client uses this interface, it doesn’t care about how the programming behind the interface (or the API) actually works. The following diagram visualizes this:

We convey ideas or thoughts through language. That’s how we do it as humans. However, computer applications need to do this too, more specifically, they need to share data. So, they do this by using APIs.

Introducing Bobby and John

To really grasp how APIs fit in with modern architecture in computer systems, we’ll go through an example. This example will outline an API that operates over the internet through the HTTP protocol. There are many other ways APIs could be designed, however, this is a fairly common instance that will support our understanding.

Let’s introduce two people, Bobby and John. John owns a time-travel center and is currently working on an app that allows people to make appointments. But he’s got a problem, sometimes people make appointments to travel back in time to an unsafe place. John is trying to figure out what he can do in order to stop this.

This is where Bobby come’s in. Bobby has wrote a program that spits out whether or not a certain time and place is dangerous. What’s more, Bobby is creating an API for his program. This API will be accessed through the HTTP protocol (this protocol is commonly used for transferring documents via the internet). If Bobby successfully implements this, John will be able to use the API for his appointments app. For the rest of this example we will refer to John’s app as the client.

Endpoints, Requests, Responses

So how are people going to access Bobby’s API? What Bobby needs is an endpoint where applications can send a request to his API. A server will live on this endpoint and handle all the request. By crunching the data it receives, it will send responses back to the respective client.

To make a request to the API, the client will specify a URI (or a Uniform Resource Identifier). The URI will contain the endpoint and the resource that the mobile app is requesting. However, the URI is not always the URL, but can be the URL — URLs are a type of URI.

The request will also contain the HTTP method. This is what you want the API to do with the data that your are sending. The main “verbs” or “methods” that are used include POST, GET, PUT, AND DELETE. These allow you to perform the CRUD operations. So you can create, read, update and delete data.

The request will also have headers and a body. The headers include meta-data about the request. So, things like the format we want for the data inside the response that will be sent back to the client. Generally, this is JavaScript Object Notation, or JSON. The headers could also include the authorization where the client can provide its credentials to tell the server who this request is coming from.

The body contains some data that the server might need. For example, if the client were creating a new resource with the HTTP POST method, it would provide some data about the resource in the body. The body is also commonly in JSON format.

So, John’s app’s request to Bobby’s API would probably look something like this:

Above, we can see that the HTTP method has been defined. In this case, the client is making a GET request to read some data. The client is also specifying which endpoint or URI it’s sending the request to. Right now, the client is sending a request to the endpoint of Bobby’s API. The client has also detailed the resource that it would like to get, in the URL. The question mark in the resource section of the URI signals that the client is going to enter some parameters. Here, in the URL, after the client specifies the location, which, in this case, is London, it also needs to tell the API the time it is asking to travel to. For this request, the client is asking about the year of 1665. The client enters a value for the parameter designated to the year.

After John’s app has made the request to Bobby’s API’s endpoint, the server on Bobby’s API will send a response. This response will have a status code. The status code will tell John’s app how things went. Hopefully, this status code is a 200 which will mean that things went alright. We’re not going to discuss HTTP status codes in this tutorial, however, there is a lot of information available about status codes on the web if you would like to dig further into how these work.

After this status code, there will also be a body for the response. The body will contain the main response data.

The response may look like this:

REST

Representational State Transfer (REST) outlines an architectural design for APIs using HTTP. An API that abides by the constraints of REST is referred to as RESTful. There is a common misconception that all APIs using HTTP are follow REST. HTTP is a protocol that we can use to share data between clients and APIs. REST, however, defines how HTTP is going to be employed. The API we have demonstrated is not necessarily, but could be RESTful. Although Bobby’s API does tick some of the boxes, we would need to know a little more about its architecture to call it RESTful.

All RESTful APIs need to:

• Be stateless (all necessary data should be included in individual requests and responses — there should be no need to store any data for the API to function)
• Employ the client-server model (that is, treat the client and server independently)
• Be cacheable (have the ability to temporarily cache requests if the server is being overwhelmed)
• Have a layered architecture (where the client is not affected by whether one or more servers are behind the endpoint)
• Have a uniform interface (there should be a consistent interface to access a resource through its URI).

What We Learnt

If we take a look at this example, Bobby figured out how to find out whether or not it is safe to travel back to a specific time. Yet John couldn’t do all that because he had a lot of other things to work on as well. He wanted to focus on the mobile app that he’s making. So, he used the API that Bobby developed and released. John doesn’t even need to care about or understand how the the program Bobby wrote functions — he just sends a single response to the API and gets sent back the data he does care about.

The API outlined in the example used HTTP to establish a gateway between the client and server. Yet as mentioned previously, it is important to understand that there are other ways this is done as well.

Hopefully, this post has been able provide some insights into this awesome technology that is so essential to the workings of countless, major computer applications.