The verbs and the answers of an API. Learn when to use GET, POST, PUT, PATCH, and DELETE, what "safe" and "idempotent" mean, and which status code (200, 201, 400, 401, 404, 500) to return.
The HTTP method is the verb — it says what you want to DO to the resource named in the URL. There are five you reach for constantly. Two words describe their behavior: "safe" means the request does not change anything (you can call it freely), and "idempotent" means calling it once or many times leaves the server in the same state (a safety net for retries on a flaky network).
// METHOD URL MEANING safe? idempotent?
GET /orders list orders yes yes
GET /orders/7 read one order yes yes
POST /orders create a new order no no
PUT /orders/7 replace order 7 entirely no yes
PATCH /orders/7 update SOME fields of order 7 no no*
DELETE /orders/7 delete order 7 no yes
// POST is NOT idempotent: sending it twice creates two orders.
// PUT IS: replacing order 7 twice leaves the same single order 7.
// That difference decides what is safe to auto-retry after a timeout.Every response starts with a three-digit status code that says how it went, grouped by the first digit. 2xx = success, 3xx = redirect, 4xx = you (the client) made a mistake, 5xx = the server broke. You do not need all of them — a handful covers almost everything. The rule of thumb: a 4xx means "do not retry this as-is, fix the request"; a 5xx means "not your fault, retrying might work."
// 2xx — it worked
200 OK // standard success (GET, PATCH, PUT)
201 Created // a POST created something new
204 No Content // success, nothing to send back (often DELETE)
// 4xx — the client got something wrong
400 Bad Request // the data you sent is invalid or malformed
401 Unauthorized // you are not logged in / no valid token
403 Forbidden // logged in, but not allowed to do this
404 Not Found // no resource at this URL
409 Conflict // clashes with current state (e.g. duplicate email)
422 Unprocessable // well-formed but fails validation rules
// 5xx — the server got something wrong
500 Internal Server Error // an unhandled error on our side
503 Service Unavailable // temporarily down / overloadedPut the two together and your API becomes predictable: clients can tell what happened without parsing the message. The biggest beginner mistake is returning 200 for everything and hiding the real result inside the body. Let the status code carry the outcome — and reserve 401 for "not logged in" versus 403 for "logged in but not allowed," because they are different fixes.
POST /orders + valid body -> 201 Created (+ the new order)
POST /orders + missing field -> 400 Bad Request
GET /orders/7 + it exists -> 200 OK
GET /orders/9999 + no such order -> 404 Not Found
DELETE /orders/7 + done -> 204 No Content
GET /orders + no token -> 401 Unauthorized
DELETE /orders/7 + not your order -> 403 Forbidden