HTTP in practice: requests, methods and status codes

The request you have not built yet

Every network example so far in this curriculum has looked like this:

let (data, response) = try await URLSession.shared.data(from: url)

That call sends a GET — a request that asks for something and sends no body with it. It is the right shape for a feed, a profile or a search result, which is why it carries most tutorials.

An app does more than read. It signs users in, saves edits, uploads receipts and moves money. Each of those sends data, and to send data you build the request yourself:

struct Payment: Encodable {
    let amountPence: Int
    let payeeID: String
}

func send(_ payment: Payment, token: String, idempotencyKey: UUID) async throws -> (Data, URLResponse) {
    var request = URLRequest(url: URL(string: "https://api.example.com/payments")!)
    request.httpMethod = "POST"
    request.httpBody = try JSONEncoder().encode(payment)
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.setValue("application/json", forHTTPHeaderField: "Accept")
    request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
    request.setValue(idempotencyKey.uuidString, forHTTPHeaderField: "Idempotency-Key")
    return try await URLSession.shared.data(for: request)
}

Four pieces of vocabulary sit in there.

A URLRequest is the whole request as a value you can hold, inspect and change before it is sent. Note that it is a var: you build it up line by line.

The method is the verb — GET, POST, and the three others below. It tells the server what kind of operation this is.

The body is the data travelling with the request. Reads usually have none. Writes carry the thing being written, almost always as JSON.

A header is a name: value pair of metadata about the request, sitting alongside the body rather than inside it. Content-Type says what the body is; Accept says what the app would like back; Authorization carries the token that proves who is calling.

Also notice the call changed. URLSession.shared.data(from: url) takes a URL and can only ever send a GET. data(for: request) takes a URLRequest, so it can send anything. In production code you almost always want the second one.

The five methods, and the one distinction that changes your code

There are five methods you will use, and any REST API you meet will be built from them:

That table is worth knowing and is not where the engineering is. Two properties cut across it, and those properties are what your networking layer actually has to reason about.

Safe means the request does not change anything on the server. GET is safe. Everything else in the table is not.

Idempotent means applying the request twice leaves the server in the same state as applying it once. The word is worth saying slowly, because it does not mean "the second attempt does nothing". It means the end state is the same either way.

PUT /profile/name with the body "Ashish" is idempotent: the name is set to "Ashish", and setting it again sets it to "Ashish". DELETE /cards/9 is idempotent: after the first one the card is gone, and a second one finds nothing to remove and leaves the world unchanged. GET is idempotent because it changes nothing at all — every safe method is automatically idempotent.

POST /payments is not. Each one creates a new payment.

Why the method decides whether a retry is allowed

Now the rule the pretest was reaching for, stated in full:

Retry a failed request only when repeating it is harmless — because the method is idempotent, or because the request carries an idempotency key.

D2-04 built the second half already. An idempotency key is a unique string the client generates once and attaches to every attempt to deliver the same operation. The server remembers keys it has already applied, so a repeat arriving with a key it has seen is recognised and ignored rather than applied again. That is what makes a POST safe to repeat when the method alone never could be.

Put the two halves together and every request can answer the question for itself:

The two POST /payments lines are the whole lesson in two lines of output. Same endpoint, same method, opposite verdicts. The only difference is a header.

This is also the join between two lessons you have already done. D2-01 taught the retry loop. D2-04 taught idempotency keys. Neither said out loud that the first one is only safe because of the second one — and that sentence is what an interviewer is listening for when they ask you to design a networking layer.

Building the URL without breaking it

Reads need query parameters — the ?q=tea&sort=newest on the end of a URL. Building that by pasting strings together is the most common way an app breaks on real user input:

// Broken as soon as anyone types a space, an ampersand or a plus sign.
let url = URL(string: "https://api.example.com/search?q=\(searchText)&sort=newest")!

A space is not legal in a URL. An & inside a value ends the value and starts a new parameter. A + means a space to many servers. So a user searching for tea & coffee sends a parameter named tea and a broken one called coffee, and the app either fails or silently searches for something else. URL(string:) returns nil for some of these, which is how the force-unwrap above becomes a crash report.

The fix is URLComponents, which percent-encodes each value for you:

var components = URLComponents(string: "https://api.example.com/search")!
components.queryItems = [
    URLQueryItem(name: "q", value: searchText),      // "tea & coffee" → tea%20%26%20coffee
    URLQueryItem(name: "sort", value: "newest"),
]
let url = components.url!

Percent-encoding is how a character that would otherwise mean something structural gets carried safely: it becomes a % and the two hex digits of its byte. A space becomes %20, an ampersand %26. The server decodes them back before it reads the value.

The simulation below builds both versions of the same search so you can see them side by side:

Read the second line of output as a server would. After q=swift 6 , the & begins a new parameter, so the search term is truncated and the server is handed a parameter named concurrency with no value. The + in c++ arrives as two spaces. Nothing throws, nothing is logged, and the user simply gets the wrong results — the same silent-wrongness failure D2-01 warned about with summary ?? "".

Headers worth sending on every request

Three headers belong on essentially every request an app makes, and a fourth is the one seniors add.

Authorization: Bearer <token> carries proof of who is calling. D2-08 is entirely about what that token is and how it stays fresh.

Content-Type describes the body you are sending — application/json for JSON. Send a JSON body without it and many servers answer 415 Unsupported Media Type, which reads like a mystery until you know this header exists.

Accept describes what you would like back. Setting application/json explicitly stops a server from deciding to send you HTML on an error path — a real cause of decode failures that look inexplicable.

The fourth one costs nothing and pays for itself the first time something goes wrong: a request id you generate yourself, a fresh UUID per request, sent in a header your backend agrees to log. When a user reports "the transfer screen hung at 14:32", a request id turns a search across several teams' logs into one lookup. D2-09 covers what else to do with it.

The status codes that change what your app does

D2-01 taught the families — 4xx is your request being refused, 5xx is the server failing — and that split carries most of the work. Below the families, a handful of individual codes each demand different behaviour, and these are the ones interviews probe:

Routed in code, that becomes a single function every screen can rely on:

401 and 403 are not the same failure

Both mean "no". They mean it for opposite reasons, and treating them alike produces one of the nastiest loops an app can ship.

401 Unauthorized means the server did not accept your token. Perhaps it expired. A new token would fix it, so the right response is to refresh and retry once.

403 Forbidden means the server accepted your token, knows exactly who you are, and this identity is not allowed to do this. A free-plan user asking for a premium report. An account without permission for a shared workspace. A new token changes nothing, because the token was never the problem.

Here is what happens when the networking layer treats 403 like 401. Follow the sequence:

1. A free-plan user opens the premium insights screen. The server answers 403.
2. The layer sees "not allowed", assumes the token is stale, and refreshes it.
3. The refresh succeeds — nothing was ever wrong with the token — so the layer retries the request with a brand-new, perfectly valid token.
4. The server answers 403 again, for the same reason as before.
5. Go to step 2.

The screen spins forever. Every loop costs two network requests, so the phone's battery drains and the auth server sees a flood of refreshes from one user, which is exactly the pattern its own rate limiter is built to punish. Eventually the auth server starts answering 429, and now the user cannot sign in on any screen — because of a report they were never entitled to see.

One case 403 prevents all of it.

429, and the number the server hands you

429 Too Many Requests means you are asking too often. Rate limiting is the server protecting itself by capping how many requests one client may make in a window.

D2-01 taught exponential backoff with jitter for the case where you have to guess how long to wait. A 429 usually removes the guessing: the response carries a Retry-After header saying how long until the limit resets. Honouring it beats any curve you invent, because the server knows when its own window opens and you do not.

Two details in that loop are deliberate. waitMillis falls back to D2-01's doubling delay when the header is absent, because Retry-After is optional and plenty of servers omit it. And the sleep is try await, never try? — the reason is the one D2-01 gave: try? swallows the CancellationError and leaves the loop running after the user has walked away.

Retry-After also appears on 503 Service Unavailable, where it means "we are down until then". The same handling covers both.