Skip to content

💫 HTTP and APIs

We've seen how the browser renders the page that we see, but how do the files get from the server to our browser, in order to be rendered ?

The magic behind this is a protocol called HTTP. Let's see what MDN has to say about HTTP:

Hypertext Transfer Protocol (HTTP) is an application-layer protocol for transmitting hypermedia documents, such as HTML. ... HTTP is a stateless protocol, meaning that the server does not keep any data (state) between two requests.

Let's break this definition down:

  • application-layer protocol - this just means that is a protocol intended to be used by an application (e.g. a browser, a server, etc.) as opposed to a protocol intended to use by hardware devices
  • hypermedia documents - hypermedia is a term extended from hypertext, and basically means any text and media (e.g. images, videos) that can be linked using hyperlinks (URLs)
  • stateless protocol - as the rest of the definition says, this means that the server doesn't keep any state between two requests. In real life use, this means that HTTP provides no way for the server to know that a request is part of a longer chain of requests, or that a specific request is associated to an user.

Although it might seem daunting at first, you'll see that HTTP is a very simple, text-based protocol. Communication in HTTP is request-response based: the client sends the server a request, and the server replies with a response. There are a few extra cases, but most of the time this is the way the protocol works.

The protocol only specifies a couple of things, the most important being the format of the request and the response.

The HTTP Request and Response formats

When the client makes a request to a server, the packet it sends needs to have the following fields:

  • A request line
  • Zero or more header fields
  • An empty line
  • An optional message body

A complete request looks a little something like this:

1
2
3
4
5
GET /hello.html HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.facebook.com
Accept-Language: en-us
Accept-Encoding: gzip

The following line:

1
GET /hello.html HTTP/1.1

is the request line. This specified the HTTP method (GET), the resource we want to request (/hello.html) and the protocol version that we are using (HTTP/1.1).

A resource in HTTP terms is any object that we can manipulate on a server. This is usually a text file (HTML, CSS, etc.) but can also be dynamic media such as images, photos or video streams.

The rest of the lines in the request are the header fields. These have the format of Key: Value, and are always entered each on one line. There are two more interesting header fields in the request above:

1
2
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.facebook.com

The first line tells the server a bit about the client that is sending the request. In this way, the server can, for example, send plaintext metadata about an image if the requester is a command-line browser, and send the complete media file if the server is a graphical one.

The next line specifies the host that we are connecting to. The resource path in the request line is relative to the Host value.

The following lines are examples that set various parameters about the client so that the server has an easier time sending a correct response.

An HTTP response looks similar to the request. The required information that the server has to include is:

  • A status line
  • Zero or more header fields
  • An empty line
  • Optionally, a message body
1
2
3
4
5
6
7
HTTP/1.1 200 OK
Date: Mon, 27 Jul 2009 12:28:53 GMT
Server: Apache/2.2.14 (Win32)
Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT
Content-Length: 88
Content-Type: text/html
Connection: Closed

Here we can see fields such as Date and Server that tell us information about the server, Last-Modified and Content-Length that tell us information about the content we have requested, and more.

The most important part of the response though is the very first line:

1
HTTP/1.1 200 OK

This tells us the HTTP version (which usually matches the one the client sends in its request) but also the status code and its meaning.

HTTP Status Codes

In order for the server to inform us about how the request went, HTTP specifies a Status Code directive. These codes are numerical values ranging from 100 to 500 that have associated human-readable strings to explain what went wrong (or right) with the request. These codes are categorized based on the first number in the code:

  • 🔵 1xx codes Informational codes. These codes usually tell us that the request has been received and we must wait.
  • 2xx codes Success codes. These codes confirm that the request was completed without problems.
  • 💫 3xx codes Redirection codes. These codes tell us that we must do something else (such as make another request at a different address) in order to complete the operation.
  • 💬 4xx codes Client error codes. These codes mean that the request that we sent was wrong or cannot be fulfilled for some reason.
  • 5xx codes Server error codes. These codes mean that the server had trouble fulfilling our request

Most of the time you'll only interact with a couple of codes:

Code Message Meaning
200 OK Request fullfilled successfully
301 REDIRECT You'll find what you're looking for at a different address
404 NOT FOUND What you requested isn't on this server
500 SERVER ERROR The server failed to deliver your request

HTTP Methods

Apart from status codes, the HTTP protocol also defines a couple of methods used to communicate with the server. Think of these as remote functions that you call on a server. Although the protocol defines many methods, in daily use we only need a couple of these:

  • GET - Requests a resource from the server (e.g. GET /index.html)
  • PUT - Adds a new resource to the server (e.g. PUT /users/new)
  • POST - Edits a resource from the server (e.g. POST /users/ion)
  • DELETE - Deletes a resource from the server (e.g. DELETE /users/andrei)

PUT and POST accept message bodies that detail, for example, how exactly a resource is to be edited, or what the new resource should contain. The GET and DELETE requests usually get all their information from the resource's location.

The browser usually makes GET requests when retrieving web pages, but it also makes POST requests when, for example, you submit an online form.

What is an API ?

An API is simply an HTTP server that, instead of responding with HTML, CSS and JS files, accepts and responds with data-specific formats such as JSON or XML. Most of today's online APIs use JSON as their format of choice. They usually are documented and are intended to be used by software programs.

APIs that respect the HTTP method descriptions above are called REST APIs, or Representational State Transfer APIs.