Methods and status codes

Methods: the verb of the request

The method at the start of the request line says what kind of action you want:

Browsers mostly send GET (every page, image, and script) and POST (form submissions, logins). The others show up constantly in APIs. A useful rule: GET must be safe, meaning it only reads and changes nothing, which is why a GET can be cached, retried, and prefetched freely (unit 8 builds on this).

REST: the convention that makes methods useful

Methods only pay off if everyone agrees what they act on. REST (Representational State Transfer) is the dominant convention for that. Every thing the server manages, whether a note, a user, or an order, is a resource with its own path, and the HTTP method is the verb applied to it:

An API built this way is called a REST API. The convention exists because the alternative was chaos. Before it, every service invented its own verbs, such as /getNote?op=del&id=17, and every integration meant reading someone's manual. With REST, an engineer who knows the resource path can usually guess the entire API. You will drive one with curl in unit 5.

Reading PATCH /users/42

It partially updates user 42, changing only the fields sent in the body.

The path names the resource, which is user 42, and the method is the verb. PATCH means a partial update, in contrast with PUT, which replaces the whole resource.

That distinction has real consequences. A PUT carrying only an email would blank out every other field, since replacing means what it says, while the PATCH leaves untouched fields alone.

Being able to read method plus path as a sentence, "update part of user 42", is exactly the value REST provides. You can predict what a request does without reading any documentation.

Status codes: the result, in one number

The first digit of the status code puts it in a class:

The 4xx/5xx split is the single most useful debugging fact in HTTP: a 4xx means your request was wrong (bad URL, missing login, no permission), a 5xx means the server broke while handling a request it understood. You will lean on this hard in the unit 9 capstone.

Classifying status codes by first digit

The first digit is the class, so a pattern like 2* matches every success code.

for code in 200 301 404 403 500 503; do
  case $code in
    2*) class="success" ;;
    3*) class="redirect" ;;
    4*) class="client error" ;;
    5*) class="server error" ;;
  esac
  echo "$code -> $class"
done

Output

200 -> success
301 -> redirect
404 -> client error
403 -> client error
500 -> server error
503 -> server error

Reading the branches

• Each branch ends with ;; and the whole statement ends with esac, the same shape as the port classifier in lesson 2-2.
• The patterns are glob patterns rather than numeric tests, so 2* matches the string starting with 2. That works here precisely because the class lives in the first character.
• Only four branches cover every code that exists, which is the design win of the numbering scheme. A client can handle an unfamiliar code correctly by looking at one digit.

Whose fault a 403 is

It is your side. The server understood the request but you lack permission for that resource.

Any 4xx means the client's request is the problem. 403 specifically means "I know who you are, and you are not allowed", in contrast with 401, which means "you have not proven who you are".

That pair is worth telling apart, because they point at different fixes. A 401 is answered by sending credentials, and a 403 is answered by changing what those credentials are permitted to do.

Retrying a 403 without changing something, whether credentials or permissions, will keep returning 403. Unlike a 503, it is not a transient condition that a backoff loop will outlast.

The method that removes a resource

The method is DELETE, so the request line reads DELETE /api/notes/17 HTTP/1.1.

The method is the verb of the request, and this action removes something, which the methods table at the top of this lesson maps directly to DELETE.

A successful delete typically answers 200 OK or 204 No Content, the latter being a 2xx success with an empty body. There is nothing meaningful left to return once the resource is gone.

Deleting something that was already deleted usually answers 404, and some APIs answer 204 anyway on the grounds that the end state is what the caller wanted. Both are defensible, so it is worth checking rather than assuming.