Anatomy of an HTTP request

Looking inside a request

In the last lesson, we saw that every web interaction is a request followed by a response. We even saw what a raw HTTP request looks like. But we moved past it quickly. Now let’s slow down and look at every part of a request, because when you build a server, your job is to read these requests and figure out what the client wants. If you do not understand the structure, you will be guessing.

The four parts of every request

Every HTTP request has up to four parts. Here is a real one:

POST /books HTTP/1.1              <- Request line (method, path, version)
Host: api.example.com             <- Headers (metadata)
Content-Type: application/json
Authorization: Bearer tok_abc123

{"title":"Kindred","genre":"sci-fi"}  <- Body (data, optional)

Let’s break this down. The first line is the request line. Below it are the headers, one per line. Then there is a blank line, and after that comes the body. The body is optional. Not every request has one.

The request line

POST /books HTTP/1.1

This single line tells the server three things, separated by spaces:

The method tells the server what action you want to perform. GET means “give me data.” POST means “create something new.” PUT means “replace this.” PATCH means “update part of this.” DELETE means “remove this.” We will cover each method in detail in the next section.

The path tells the server which resource you are acting on. /books means “the collection of books.” /books/book-1 means “the specific book with ID book-1.” /users/me/orders means “my orders.” The path can also include query parameters: /books?genre=fiction&page=2 means “give me books filtered by genre fiction, page 2.”

The version says which HTTP version this request uses. Almost always HTTP/1.1 in text representations. You do not need to worry about this much, but it is there.

Headers: metadata about the request

Below the request line, you will find the headers. Headers are key-value pairs that carry extra information about the request. Think of them as instructions or context for the server.

Host: api.example.com
Content-Type: application/json
Authorization: Bearer tok_abc123
Accept: application/json
User-Agent: Mozilla/5.0

Here is what each of these does:

Host tells the server which website the client wants. This might seem unnecessary (you already connected to the server, right?), but a single server at one IP address can host multiple websites. The Host header tells it which one you are looking for. It is required in HTTP/1.1.

Content-Type tells the server what format the request body is in. application/json means “the body is JSON.” application/x-www-form-urlencoded means “the body is form data.” This header is only needed when the request has a body. If there is no body, there is nothing to describe.

Authorization carries credentials for authentication. Bearer tok_abc123 is a token that proves who the client is. This is how your server knows whether someone is logged in.

Accept tells the server what format the client wants the response in. application/json means “please send me JSON.”

User-Agent identifies the client making the request. Browsers send long, detailed strings. curl sends curl/7.x. Your own application can send whatever it wants.

Section 4 of this course covers headers in much more depth. For now, just know they are there and what they do.

The body: data the client sends

The body is where the client puts data it wants to send to the server. Not every request has a body.

Requests that have a body: POST (you are sending data to create something), PUT (you are sending the full replacement), PATCH (you are sending the fields to update).

Requests with no body: GET (you are just asking for data), DELETE (you are just saying “remove this”), HEAD, OPTIONS.

What do you think happens if you send a body but do not include a Content-Type header? The server has no idea how to read the body. It does not know if those bytes are JSON, form data, or plain text. The Content-Type header is what makes the body interpretable. The Content-Length header also comes along, telling the server how many bytes to expect.

Seeing a request with curl

You can watch a real request happen using curl with the -v flag:

curl -v -X POST https://api.example.com/books \
  -H "Content-Type: application/json" \
  -d '{"title":"Kindred"}'

Lines starting with > are the outgoing request:

> POST /books HTTP/1.1
> Host: api.example.com
> Content-Type: application/json
> Content-Length: 19
>
> {"title":"Kindred"}

There it is. The request line (POST /books HTTP/1.1), the headers (Host, Content-Type, Content-Length), the blank line, and the body ({"title":"Kindred"}). Everything we just talked about, in one place.

Now that we know what the client sends, the next lesson looks at the other half: what the server sends back.

Exercises

Exercise 1: Use curl -v to make a GET request to any URL. Identify the request line and headers. Notice there is no body.

Exercise 2: Use curl -v to make a POST request with a JSON body. Find the Content-Type header and the body in the output.

Exercise 3: Open your browser’s developer tools, navigate to a page, and click on any request in the Network tab. Find the method, path, headers, and body.