GET and HEAD

The method you already know

In the previous section, we looked at the structure of HTTP requests and responses. We saw that the very first word on the request line is the method, and it tells the server what you want to do. Now let’s dig into each method, starting with the one you use all the time without even thinking about it: GET.

Every time you click a link, type a URL, or open a bookmark, your browser sends a GET request. It is by far the most common HTTP method, and its job is simple: read data and give it back.

GET: asking for data

GET /books HTTP/1.1
Host: api.example.com
Accept: application/json

This says: “Give me the resource at /books.” The server looks at that path, finds the data, and sends it back. GET does not change anything on the server. It only reads.

Notice there is no body. GET requests carry all their information in the URL and headers. If you need to pass parameters (like filtering or pagination), they go in the query string: /books?genre=fiction&page=2. Not in a body.

Safe methods

GET is what is called a safe method. “Safe” means the request does not change anything on the server. You can call GET /books a hundred times and it reads the same list every time. It does not create books, delete books, or modify anything.

Why does this matter? Because browsers, CDNs, and proxies assume GET is safe. They freely cache GET responses and replay GET requests. If GET actually modified data on your server, caching would cause all sorts of problems. Imagine a cached response creating a duplicate order every time someone’s browser replayed the request. That is exactly why this distinction exists.

Idempotent methods

GET is also idempotent. That is a big word, but the idea is straightforward: calling the request once has the same result as calling it a hundred times. Since GET does not change anything, the result is always the same.

This is really useful for error handling. If a GET request fails because of a flaky network, the client can safely retry it. There is no risk of accidentally creating duplicates or causing side effects, because GET does not have side effects.

[!NOTE] The REST API Design course uses idempotency as a core design principle. This lesson explains where the idea comes from: the HTTP specification itself defines which methods are safe and which are idempotent.

HEAD: GET without the body

HEAD is a method you might not have seen before. It works exactly like GET, except the server does not send a response body. You get the status code and headers, but no data.

HEAD /books/book-1 HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 52

No body. Just the headers.

Why would you want that? A few reasons: you want to check if a resource exists without downloading all the data. You want to check a file’s size (via Content-Length) before deciding whether to download it. You want to check if data has changed (using ETags, which we cover in the Caching course). HEAD gives you metadata without the cost of transferring the full response.

Now that we know how to read data, the next lesson covers the method for creating it: POST.

Exercises

Exercise 1: Make a GET request with curl -v. Identify the method on the request line and the body in the response.

Exercise 2: Make a HEAD request with curl -I. Compare the headers to what you got from the GET response. The headers should match, but there is no body.

Exercise 3: Make a GET request with query parameters: curl "https://api.example.com/books?genre=fiction". Notice how the parameters are part of the URL, not the body.