REST and CRUD: resources, methods, status codes

In the API step of a design round, you list the requests a client can send. Interviewers expect the path, the method and the status code for each.

A weak answer uses verbs in every path, sends everything as POST, and returns 200 for every result. A strong answer uses nouns, picks the right method and code, and says which calls can be sent twice without harm.

Think about a library. Each book has a shelf label. You can add a book, look at it, replace it or remove it.

A resource is a thing the API keeps, such as an order. /orders means all orders. /orders/42 means order 42. Use plural nouns, not verbs. In lesson 2, the call getResult(rollNumber) becomes GET /results/4821.

REST is a style of API in which resources have URLs and HTTP methods say what to do. Each request carries all that the server needs, because the server keeps no memory of earlier requests (lesson 7).

CRUD means create, read, update, delete: the four things you do with stored data. Each one has a method, the action word in the request. Two words help you compare methods:

• A method is safe if it only reads: it asks the server to change nothing.
• A method is idempotent if sending the same request many times leaves the server in the same state as sending it once. This is about the state, not the answer.

This matters because a request can arrive twice: a user taps twice, or the app sends again after a lost answer. An idempotent request can be sent again without harm.

PATCH depends on the change. "Set the quantity to 2" gives the same state every time. "Add 1 to the quantity" does not.

The status code tells the client what happened. Its first digit gives the family:

• 2xx means success. 200 OK. 201 Created (after a POST, with the new URL in a Location header). 204 No Content (success, nothing to send back).
• 3xx means redirect (lesson 7).
• 4xx means the client made a mistake. 400 Bad Request (bad input). 401 Unauthorized (not logged in). 403 Forbidden (logged in, but not allowed). 404 Not Found. 409 Conflict (the request clashes with saved data, such as an email already in use).
• 5xx means the server failed. 500 Internal Server Error.

Assumption: product 7 costs Rs 250. The cart is cart 9. The server gives each cart line its own number.

POST   /carts/9/items      body {"product": 7, "quantity": 1}  -> 201 Created, Location: /carts/9/items/1
GET    /carts/9/items/1                                        -> 200 OK
PUT    /carts/9/items/1    body {"product": 7, "quantity": 1}  -> 200 OK
DELETE /carts/9/items/1                                        -> 204 No Content

Now the three taps.

• POST adds a new line each time. That makes 3 lines. Total = 3 x Rs 250 = Rs 750.
• PUT sets line 1 to quantity 1. Three requests leave the quantity at 1. Total = 1 x Rs 250 = Rs 250.

PUT is the answer to the predict box. Now DELETE. The first request returns 204 and line 1 is gone. A second returns 404. The answers differ, but the state is the same: no line 1. So DELETE is idempotent.

• REST solves the need for a simple API that every client and tool understands. It costs a poor fit for actions that are not nouns, such as "cancel an order". I would write POST /orders/42/cancel for those.
• PUT solves double taps, because it is idempotent. It costs more bytes, because you send the whole resource. I would change to PATCH for a large resource, if the change can be repeated without harm.

"POST is for create, PUT is for update, always." Not always. PUT creates a resource when the client picks the address.

"Idempotent means the answer is always the same." It means the state is the same. A second DELETE returns 404, and DELETE is still idempotent.

"Return 200 for everything, and put the error in the body." Clients read the code. A 200 with an error hides failures. Use 4xx and 5xx.

1. Which of GET, POST, PUT, PATCH and DELETE are idempotent? What does "safe" mean?
2. An item costs Rs 250. The app sends the same request 4 times. What is the cart total if it was (a) a POST that adds a line, (b) a PUT that sets the quantity to 2?
3. You design a call that changes the delivery address of order 42. Which method do you use? Which code do you return if the user is not logged in, is logged in as another user, or sends an empty address?