Mobile system design, from a packet to an app · Puzzle 2 · 3 of 11

Anatomy of an HTTP call

Retrofit hides the request behind an annotation and hands you an object back. The rest of this course reads the parts it hides. Here they are, once, mapped to the Retrofit code you already write.

The problem

You write @GET("users/42") and get a User. When something fails, Retrofit gives you a code like 404 or 503, and later puzzles talk about parts of the request it hides. What exactly travels, and what do those numbers mean?

See it

A GET request to /users/42 with an Authorization header travels to the server; the response comes back with status 200 OK, headers and a JSON body; status codes are grouped in families 2xx 3xx 4xx 5xx app server GET /users/42Authorization: …no body 200 OKContent-Type: json{ "name": "Anna" } 2xx worked · 3xx elsewhere4xx your fault · 5xx theirs 404: don't just retry
  1. A request: an HTTP method (GET), a path, headers about the message, and here no body.

    Step 1 of 4
  2. The response: a status code, its own headers, and the JSON body.

    Step 2 of 4
  3. Status codes come in families by first digit. Predict: a 404, should you retry?

    Step 3 of 4
  4. No: a 4xx says your request was wrong, so the same request will fail again. A 5xx might pass later.

    Step 4 of 4

The building block

An HTTP request has four parts:

PartExampleIn Retrofit
HTTP methodGET, POST, PUT, DELETE@GET, @POST…
path/users/42the annotation's string
headersAuthorization: Bearer …@Header, or an interceptor
bodyJSON of a new order@Body

The method says what you want: GET reads, POST creates something new, PUT replaces something at that path, DELETE removes it. Headers are name–value pairs about the message, not the data itself: who you are, what format you accept, how long something may be cached.

The response comes back with a status code, headers, and a body. Status codes come in families, by their first digit:

FamilyMeaningExamples
2xxit worked200 OK, 201 Created
3xxlook elsewhere, or use what you have301 Moved Permanently
4xxyour request was wrong400 Bad Request, 401, 404, 429 Too Many Requests
5xxthe server failed500, 503

The family is what your code usually decides on: a 4xx won't fix itself if you send the same request again; a 5xx might.

The analogy

A letter to an office: the method is what you're asking for ("please file this", "please send me that"), the path is which department, the headers are the notes on the envelope, the body is the letter. The reply comes with a stamp: approved, see the other office, your form is wrong, or we're closed.

Check yourself

Your app gets a 404 from GET /users/42. Should it retry the same request?

Right. 4xx won't fix itself.

Not quite. Changing the method changes the meaning; it doesn't fix a missing user.

Not quite. Only server failures (5xx) might pass; a 4xx is about your request.

Where does a request say "this response can be cached for a minute"?

Right. Notes about the message: headers.

Not quite. The body is the data; notes about the message go in headers.

Not quite. Status codes say how it went; caching rules travel in headers.

What's the difference between GET and POST?

Not quite. That's the two swapped. Re-read that part ↑

Right. Read vs create.

Sources

  • MDN: An overview of HTTP ("HTTP headers make this protocol easy to extend and experiment with"; requests and responses as HTTP messages)
  • MDN: HTTP response status codes ("Responses are grouped in five classes: Informational responses (100 – 199), Successful responses (200 – 299), Redirection messages (300 – 399), Client error responses (400 – 499), Server error responses (500 – 599)")

What you now know

An HTTP request is a method (GET to read, POST to create, PUT to replace, DELETE to remove), a path, headers (name: value pairs about the message) and an optional body. The response has a status code, headers and a body. Status codes come in families: 2xx worked, 3xx look elsewhere or use what you have, 4xx your request was wrong, 5xx the server failed.