Every web page starts with a request
HTTP (HyperText Transfer Protocol) is the set of rules a browser or an app uses to talk to a server. A client asks for something and the server answers. Every web page, every app feed and every API call is made of the same two messages: a request and a response.
Once you can read those two messages, you can see what any app sends and what it gets back.
By the end of this lesson
Note
I can read an HTTP request and its response.
Key words
| Word | What it means | Example |
|---|---|---|
| Request | the message a client sends to ask for something | |
| Response | the message a server sends back | |
| Method | the word that says what to do | GET |
| Header | one line of extra detail, written as a name and a value | Accept: application/json |
| Status code | a three-digit number saying how the request went | 404 |
| Body | the data a message carries |
The cells students fill in are left blank in this preview.
A request has four parts
A client is the program that asks, such as a browser or a phone app. A server is the program that answers.
The first line of a request holds the method and the path. A method is one word that says what to do: GET reads and POST adds. The path says which thing. After that come header lines, and sometimes a body that carries data.
A request, line by line (an example)
POST /books HTTP/1.1
Host: library.example
Content-Type: application/json
Accept: application/json
{"title": "Tide Tables", "year": 2019}
# Line 1: method POST, path /books, protocol version.
# Lines 2 to 4: headers. Host names the server.
# The blank line ends the headers. What follows is the body.Make a small library catalogue to query
This lab has a database and an API in front of it. You will ask the API about a table of library books.
Run the next two commands. The first gives psql, the database client, its password. The second makes a books table with three rows. Neither prints an answer you need to read.
Give psql the password
export PGPASSWORD=shopShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Make the books table
psql -h db -U shop -c "drop table if exists books; create table books (id serial primary key, title text not null, year int not null, available boolean not null default true); insert into books (title, year, available) values ('Maps of the Sea', 1998, true), ('Rivers of Europe', 2004, false), ('Night Trains', 2011, true); notify pgrst, 'reload schema'"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Print only the status code
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/books"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
A response has three parts
The first line of a response holds the status code, a three-digit number. 200 means the request worked. 404 means nothing was found at that path.
Headers follow. Content-Type says what kind of data the body holds. Then comes the body: the rows, the page or the error.
A response, line by line (an example)
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[{"id":2,"title":"Rivers of Europe","year":2004,"available":false}]
# Line 1: protocol version, status code 200, its short name OK.
# Line 2: a header. The body is JSON, so a program can read it.
# After the blank line: the body, one book in a list.Print the Content-Type header of the answer
curl -s -o /dev/null -w "%{content_type}\n" "http://api:3000/books"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Ask for a path that does not exist
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/nothing"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
A common mistake
Warning
Many people think a 404 means the server is down. It does not. A 404 is an answer: the server heard you and found nothing at that path. A server that is really down gives no response at all.
curl sends a request from the terminal
curl is a command-line tool that sends a request and shows the response. It lets you see exactly what an app would send.
You change the request with flags. -X sets the method and -H adds a header. -d sets the body. -s keeps curl quiet, and -w prints one chosen fact about the response, such as the status code.
Worked example: what each curl flag changes
| Flag | Part of the exchange it changes | Example |
|---|---|---|
| -X | The method | -X DELETE |
| -H | A header | -H "Accept: text/csv" |
| -d | The body | -d '{"year":2020}' |
| -w | What curl prints afterwards | -w "%{http_code}" |
| -o /dev/null | Throws the body away, so only -w shows | -o /dev/null |
The cells students fill in are left blank in this preview.
Ask for CSV with an Accept header
curl -s -o /dev/null -w "%{content_type}\n" -H "Accept: text/csv" "http://api:3000/books"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.