GET, read without touching

GET retrieves a resource or a collection of resources. It should never modify data on the server. This is what "safe" means: calling it leaves the world in the same state as before.

GET /api/users/123
GET /api/users
GET /api/users?role=admin&active=true

GET is also idempotentWhat is idempotent?An operation that produces the same result whether you perform it once or multiple times, making retries safe. Ask AI for more, making the same request ten times returns the same result as making it once (assuming the data hasn't changed). That's what makes GET cacheable. Browsers, CDNs, and proxies can all cache GET responses automatically.

POST, create something new

POST creates a new resource. The server decides where to put it (the new resource's URI is returned in the Location header). POST is neither safe nor idempotentWhat is idempotent?An operation that produces the same result whether you perform it once or multiple times, making retries safe. Ask AI for more, clicking submit twice creates two records.

POST /api/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

The correct response is 201 Created with a Location header pointing to the new resource:

HTTP/1.1 201 Created
Location: /api/users/124

{
  "id": 124,
  "name": "John Doe",
  "email": "john@example.com"
}

PUT, replace entirely

PUT replaces the entire resource with whatever you send. If you PUT a user object that's missing the phone field, the phone gets wiped out. You must send the complete resource.

PUT /api/users/123
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "age": 30
}

PUT is idempotentWhat is idempotent?An operation that produces the same result whether you perform it once or multiple times, making retries safe. Ask AI for more, putting the same data twice has the same result as putting it once. Returns 200 OK with the updated resource, or 204 No Content if you don't want to send a body back.

PATCH, update partially

PATCH applies partial modifications. You only send the fields you want to change.

PATCH /api/users/123
Content-Type: application/json

{
  "email": "newemail@example.com"
}

This is more bandwidthWhat is bandwidth?How much data can flow through a connection at once - like the number of lanes on a highway rather than the speed limit. Ask AI for more-efficient than PUT for large resources, but it requires the server to merge the patch carefully. PATCH is not guaranteed to be idempotentWhat is idempotent?An operation that produces the same result whether you perform it once or multiple times, making retries safe. Ask AI for more, it depends on the implementation.

DELETE, remove it

DELETE removes a resource. It's idempotentWhat is idempotent?An operation that produces the same result whether you perform it once or multiple times, making retries safe. Ask AI for more in the sense that deleting a resource that no longer exists should return the same result (usually 404 or 204) rather than an error.

DELETE /api/users/123

Returns 204 No Content (most common) or 200 OK with a confirmation body if you want to be verbose.

Status codes you'll actually use

Status codes are grouped by meaning. The first digit tells you the category; the restWhat is rest?An architectural style for web APIs where URLs represent resources (nouns) and HTTP methods (GET, POST, PUT, DELETE) represent actions on those resources. Ask AI for more give you the specifics.

2xx, it worked

4xx, the client did something wrong

5xx, the server broke

Method properties at a glance