GET, POST, PUT, PATCH and DELETE, plus the status codes you will see every day. A plain guide to choosing the right ones when you build or call an API.
Every time your app talks to an API, two small things carry most of the meaning: the method you send (like GET or POST) and the status code you get back (like 200 or 404). Get them right and your API is easy to use. Get them wrong and everyone who calls it has to guess.
By the end you will be able to:
- Choose the right method for reading, creating, replacing, updating and deleting.
- Explain what “safe” and “idempotent” mean in plain words.
- Pick sensible status codes for success and failure.
- Tell 401 and 403 apart, and 400 and 422 apart.
A request and a response
HTTP is a conversation. The client sends a request made of a method, a path and sometimes a body. The server replies with a response made of a status code and usually a body.
The five methods you need
| Method | Use it to | Typical path | Success code |
|---|---|---|---|
GET | Read data | /users/42 | 200 |
POST | Create something new | /users | 201 |
PUT | Replace a whole item | /users/42 | 200 or 204 |
PATCH | Change part of an item | /users/42 | 200 |
DELETE | Remove an item | /users/42 | 204 |
Notice the paths are nouns (/users), not verbs (/getUsers). The method already says what to do, so the path only needs to say what it is done to.
Safe and idempotent, in plain words
Two words come up a lot. They sound academic but the ideas are simple.
- Safe means the request does not change anything on the server. Reading is safe.
- Idempotent means doing it once or ten times leaves the server in the same state. Deleting user 42 ten times still leaves them deleted.
| Method | Safe? | Idempotent? |
|---|---|---|
GET | Yes | Yes |
PUT | No | Yes |
DELETE | No | Yes |
PATCH | No | Not guaranteed |
POST | No | No |
Why care? Networks fail. If a request times out, a client can safely retry an idempotent call. Retrying a POST might create two orders, which is why payment APIs ask for an idempotency key.
Status codes: read the first digit
You do not need to memorize sixty codes. The first digit tells you the story, and a handful of specific codes cover most real work.
| Code | Meaning | When to use it |
|---|---|---|
200 | OK | Request worked and there is a body to return |
201 | Created | A POST made something new. Include its location |
204 | No Content | Worked, nothing to return, like a DELETE |
400 | Bad Request | The request is malformed, for example broken JSON |
401 | Unauthorized | Not logged in, or the token is missing or expired |
403 | Forbidden | Logged in, but not allowed to do this |
404 | Not Found | That item does not exist |
409 | Conflict | Clashes with current state, like a duplicate email |
422 | Unprocessable | Valid JSON, but the values break a rule |
429 | Too Many Requests | Rate limit hit. Say when to retry |
500 | Server Error | Something unexpected broke on our side |
503 | Unavailable | Temporarily down or overloaded |
Two pairs people mix up
401 versus 403
401 is about who you are: “I do not know you, please sign in.” 403 is about what you may do: “I know who you are, and the answer is no.”
400 versus 422
Use 400 when the server cannot even understand the request, such as invalid JSON. Use 422 when it understood fine, but the content breaks a rule, such as an email without an @.
A good error response
A status code alone is not enough. Return a small, consistent body so developers know what to fix:
{
"error": {
"code": "invalid_email",
"message": "The email address must contain an @ sign.",
"field": "email"
}
}