API Architecture: The HTTP Protocol and Its Importance

If you have the time, stop and think for a minute about what the software landscape would look like without APIs.

Pretty hard to imagine, right? I’ve been thinking about this very topic for a while and concluded that APIs are among the cornerstones of the interconnected world we live in. But how did they achieve that? How can APIs act as the bridge to so many different software products and not become impossibly complex?

The short answer is that it uses strict protocols, conventions that dictate how the programs interact with the API.

The long answer is this whole article. So, if I’ve captured your attention, let’s take a look together at how application programming interfaces became the glue that keeps software together.

Protocols — The rules of conduct in computer science

While people have made great strides in artificial intelligence and machine learning, efficient data transfer still requires rigid regulations. The more standardization there is in requests and responses, the less likely it is that something will go wrong.

Let’s draw a simple parallel between computers and people.

If you introduce yourself to someone, you can either say your name, followed by your surname, or vice versa. Either way, the listener will easily understand which is your name and which is your surname.

If you introduce yourself to a computer, things aren’t that simple. Both the name and surname are just strings of characters for the computer. While machine learning algorithms might help it guess which is which, this would be overcomplicating and wasteful. The simple solution is this: the computer should expect the name and then the surname. You, the human, should give the information in that order. As long as both you and the computer agree to this convention, transferring data is easy.

For interaction between two computers or pieces of software, the conventions are just as rigid, if not more so. In computer science, these rules are called protocols. They dictate how the sender formats their message (down to the last detail) and how the receiver interprets that message.

The importance of protocols for APIs

As you know, application programming interfaces serve as bridges between at least two apps. They can facilitate communication over the web, in which case they’re called web services, and follow web protocols (most likely HTTP). Alternatively, they can connect two internal pieces of software on a private network, in which case the developers can create whatever protocols they want.

As long as one program’s function is called and a request goes to retrieve data from a different program, this interaction is an API. The important part is that the communication happens successfully. So, the API’s role is to ensure that both the request and response between apps are understood. That’s why protocols are a must.

Another important factor besides the protocol is the format.

Think back to the “name, surname” example I presented. What if the computer asked me to type out my identity and instead I sent an audio file of me saying my name and surname? Even if the order is correct, the format isn’t. The computer didn’t expect an audio file, and it doesn’t know how to interpret it.

HTTP — The crucial web protocol

Hyper-Text Transfer Protocol, or HTTP, is the primary protocol for any kind of web-based communication. Since it’s so widely spread and plenty of APIs are built to operate over the Internet, it’s no wonder that plenty of APIs have adopted HTTP as their standard protocol as well.

From an objective point of view, choosing HTTP as the protocol for the API gives you a few key advantages:

• Most developers are familiar with the protocol, so it’s easy to use, update and scale.
• It requires little processing by the apps, so it’s faster than other protocols.
• Its flexibility means that APIs built on it can accomplish a wide variety of objectives.
• Responses can be cached, meaning that repeated commands are processed faster.

HTTP is a request-response protocol, meaning that any interaction between two parties is composed of a request and a response. The client issues the request to the server, and then the server sends a response to the client, even if it can’t fulfil the request.

Requests and responses have different formats. To better understand how HTTP and protocols in general function, let’s look at the architecture of both.

The structure of HTTP requests

A valid HTTP request has four components: an URL (Uniform Resource Locator), a method, a list of headers, and a body.

URL

The URL is the unique address for a thing on the server. “Thing” doesn’t sound very scientific, so we’ll go with the technical name — resource. Resources can be anything, ranging from web pages to images to more abstract files pertaining to things like personal profiles, usually stored in JSON or XML format.

When referring to resources, you’ll often hear them called nouns too. This is more of an API design principle since all resources should be given nouns as names to simplify the use of the API. You’ll see in a second why.

Method

The method tells the server what kind of action the client wants. Since it’s an action, developers also refer to the method as the verb. That’s why resources shouldn’t be given verbs as names. It cuts down on possible confusions.

There are several possible methods, but for RESTful APIs, the most common five are these:

• GET — used to retrieve or read a resource. If successful, the response will contain the resource specified in the URL. APIs mainly deal in JSOn and XML files.
• POST — used to create new resources, including subordinate resources to already existing nouns. A successful response will contain the URL of the newly created resource.
• PUT — used to update an existing resource. The request will also contain the new information that should replace the existing one in the resource.
• PATCH — like PUT, updates an existing resource, but differently. Instead of sending the new data, it sends instructions on how to modify the current resource.
• DELETE — used to, as the name suggests, delete a resource.

Headers

By adding headers to a request, you include meta-information, which can help the overall process.

For example, the Content-Type header declares the format of the data present in the request’s body. If the body contains an XML file, this header is necessary to help the server understand how to process the said file.

The Accept header also specifies a data format but for the response instead of the request. If you need to retrieve a JSON file, for example, you’ll use the GET method and set the Accept header to only accept data in JSON format.

These are just two examples of headers, but there are many more out there. There are plenty of header options just for the client authentication process. Which ones you’ll use depend on your needs and objectives for the API.

Body

This part of the request contains the information you want to send to the server. You can add just about any sort of data. Just remember to specify it in the headers.

For requests that manipulate existing resources or create new ones, the body will contain the data for the action.

The structure of HTTP responses

While similar to requests, responses have one key difference: the URL and method are replaced by a status code. So, the response is composed of a status code, a list of headers, and a body.

Since you’re already familiar with headers and the body of a message, we’ll only focus on what’s different:

Status Code

A status code is a three-digit number that the server uses to tell the client the result of its request.

You know how in military movies, whenever someone is talking over the radio, the listener will say at the end something to the effect of “Copy that.”? The meaning of that response is to notify the speaker that the message has been received and understood. The status code is a computer’s version of that response. When the server returns a status code between 200 and 299, it’s telling the client “Copy that.”.

Each code has its own meaning but they can all be grouped into one of five classes:

• 100–199: informational responses
• 200–299: successful responses
• 300–399: redirects
• 400–499: client errors
• 500–599: server errors

That’s it for the HTTP protocol.

As you can see, the structure is both versatile and easy to understand for humans. These features have made HTTP the bedrock of web interactions and the choice protocol for RESTful APIs.

The power of HTTP APIs

Like any API, application programming interfaces built on the HTTP protocol enable different software products to seamlessly integrate while also staying fundamentally different. HTTP APIs support cross-software communication without limiting the functionalities of the programs themselves.

Another great thing about HTTP is that it’s cacheable. If the server sends some data that you expect to use again soon, just add a header to the response and the response, and that information can be saved locally to the client. This way, the next time the client requests the data, they immediately receive it from their cache. This principle can save a lot of time and bandwidth for APIs that deal with large amounts of data.

One last advantage of HTTP is just how widespread and well-known it is. If a public API runs on HTTP, it’s exceedingly easy for any developer to integrate said API with their own software. Since an APIs core objective is to simplify data transfer, a popular protocol does wonders in eliminating ID-10T errors.

In most cases, an HTTP API is the same thing as a REST API since HTTP is the standard protocol for REST APIs. The difference is that an API isn’t RESTful just because it uses HTTP. Other architecture rules must be applied before you can call an HTTP API RESTful.

Intrigued? I thought you’d be.

That’s why I recommend you also read this article on the differences between REST and SOAP APIs. After all, protocols aren’t everything.