This chapter will review the basics of how HTTP works, but only as much as is needed to discuss concepts related to web APIs. The next chapter will cover URLs, and following that will be a discussion of data serialization. Just as humans use names to identify each other, speech to create sounds and language to interpret those sounds into meaning, computers use these technologies to communicate with each other: URLs describe what resource is being targeted, HTTP defines how systems send messages about these resources, and data formats allow these messages to be converted into data that is then acted on.
The technologies of the web enable collaboration between systems. Let's start with the backbone of these communications, HTTP.
Web APIs are based on the same technologies that allow websites, web browsers, and web servers to work: HTTP.
HTTP, or Hypertext Transfer Protocol, describes how a client program (such as a web browser) interacts with servers. These interactions are based on a request-response pattern, where the client asks the server for something it wants (the request) and the server then sends something back (the response.) The web, as complicated as it can seem, is almost entirely built on top of this model of sequential requests and responses.
For example, if a person types http://google.com into the address bar of their browser, the browser will request a page from the server at google.com. The server's response is then interpreted by the browser and displayed to the user. Each image, stylesheet, and script file referenced in the rendered page is loaded in the same way: the browser makes a request to the server, receives a response, and then does something with it. In this way, multiple requests and responses are used together to achieve a larger goal (in this case, the display of an entire webpage).
APIs work in basically the same way, only instead of a human making requests through a web browser, API requests are usually made from one computer program to another. As a developer, you can call APIs from your own programs. This can enable your programs to do all kinds of things that would be difficult or impossible to do by themselves.
We've already looked at how requests can be made with Postman. It is also possible to explore some APIs from the command line, and we will use that as an example to review some important HTTP concepts.
To run the command shown below, you first need to sign up for a free account at IP API. Click the Sign Up to Run API Request button and fill out the form. Don't forget to save your access key.
Entering the following command in a terminal will retrieve a bunch of information about the the IP 161.185.160.93, including the country where it is located:
$ http http://api.ipapi.com/161.185.160.93?access_key=YOUR-ACCESS-KEY-HERE --json
# If using Zsh, run this command instead:
% http 'http://api.ipapi.com/161.185.160.93?access_key=YOUR-ACCESS-KEY-HERE' --json
The --json option isn't strictly required here, but we include it just in case the API gets updated.
Like most of the web, the request and response are text-based, which makes things fairly easy for us to look at and understand as humans. We can break the response into three main parts: the status code, the headers, and the body.
The first line of the response looks like this:
HTTP/1.1 200 OK
The important part of this line is the last part, 200 OK. All HTTP responses will start with a three digit numeric code and message that summarize the result of the preceding request. There are a lot of status codes, and there is no need to try to remember them all because they are easy to look up as needed. There are, however, a few basic rules to interpreting these codes that will come in handy:
200 or 201, it means that everything is fine and the request was handled successfully.
303, means that the request was handled successfully, but the response to the request is located at a different URL, which is usually provided in a header (we'll talk about headers next.) 3xx statuses are commonly used by a server to respond to a HTML form POST submission. They are much less commonly used when working with HTTP APIs.
404, means that the client did something in the request that the server didn't like. It often means that a required parameter was forgotten or that the URL is incorrect.
500, means that the server encountered an error processing the request. Usually this means that the system you are connecting to is having issues that need to be resolved by those who run it before you can continue, although sometimes it can also be the result of a bad request.
It's worth noting that servers don't always return the correct status code, often as a result of a programming oversight. This will be covered in depth in a future course; for now, know that it is sometimes necessary to look at the entire response for clues as to what is happening when you have received a status code that doesn't make sense.
The next section of the response includes a lot of detailed information, such as when the response was created, the name of the server handling the request, and a lot more:
CF-Cache-Status: DYNAMIC
CF-RAY: 7694e9094d32ef9c-PDX
Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
Date: Sun, 13 Nov 2022 04:54:35 GMT
NEL: {"success_fraction":0,"report_to":"cf-nel","max_age":604800}
Report-To: {"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report\/v3?s=VJQHe9u15PD8yXpSY0ZwfioL2qi8iHUOoiQLdEzMKnAnIrmmrtM6caxSquhaKkJuzMVBs3GHty42saK3qQsqqgjBSTuw0yeGlgAmXaJ3vItVuCcntg4vPOUfvQC%2FeyUOEmdN0C9DqoxDMqSA"}],"group":"cf-nel","max_age":604800}
Server: cloudflare
Transfer-Encoding: chunked
access-control-allow-headers: *
access-control-allow-methods: GET, POST, HEAD, OPTIONS
access-control-allow-origin: *
alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400
x-apilayer-transaction-id: 113aa789-ec14-4759-bb75-972b61f7b70f
x-increment-usage: 1
x-quota-limit: 1000
x-quota-remaining: 996
x-request-time: 0.031
The most important line is the one that defines the response's Content Type:
Content-Type: application/json
The content type describes the format of the rest of the response's content. This response's content type is application/json, which means we can interpret the body as JSON.
The rest of the headers specify other pieces of information about the response. There are a lot of headers that can be used, and systems can even define their own. We will cover some additional headers as we encounter them throughout our exploration of APIs, and there is a list of some common ones in the appendix.
By looking at the content type of the response body, we know that the rest of the response is in JSON format. HTTPie notices this and prints out the response body in a way that is more suitable for human consumption:
{
"city": "Coney Island",
"continent_code": "NA",
"continent_name": "North America",
"country_code": "US",
"country_name": "United States",
"ip": "161.185.160.93",
"latitude": 40.69459915161133,
"location": {
"calling_code": "1",
"capital": "Washington D.C.",
"country_flag": "https://assets.ipstack.com/flags/us.svg",
"country_flag_emoji": "🇺🇸",
"country_flag_emoji_unicode": "U+1F1FA U+1F1F8",
"geoname_id": 5113481,
"is_eu": false,
"languages": [
{
"code": "en",
"name": "English",
"native": "English"
}
]
},
"longitude": -73.99063873291016,
"region_code": "NY",
"region_name": "New York",
"type": "ipv4",
"zip": "11201"
}
You can see that this IP is in the United States. If you run the command with an IP from a different country, you will, of course, see different data. The structure of the data should be similar, though.
A program that is making a call to an API such as this one would probably pull a few pieces of data out of this payload and do something with it. An app that displayed the current value of a stock portfolio might just need the current price and maybe the high and low values to display to a user. To do this, the app could parse the JSON and then access the parts it cared about.
Parsing is the process of converting data from one format (often one that is designed to transfer or persist the data) into a representation that is easier to work with for a computer. When a web browser loads an HTML page, one of the first things it does is parse the HTML text into an internal representation used to draw the page on a screen.