The Full CRUD Lifecycle
You'll learn to
- -Distinguish PUT (full replace) from PATCH (partial update) and pick the right one for a given operation
- -Use 201 Created with a Location header and 204 No Content correctly, instead of defaulting every response to 200
Create, Read, Update, Delete looks trivial until the details are actually specified - and the details (which status code, which method for "update," what the response body contains) are exactly what separates a REST API that behaves predictably from one that makes every client guess.
PUT vs. PATCH: Replace vs. Modify
# PUT: the body is the COMPLETE new representation of the resource.
# Any field omitted from the body is treated as cleared/reset, not "unchanged".
PUT /users/42
{"name": "Ada Lovelace", "email": "ada@example.com", "role": "admin"}
# PATCH: the body describes only what changes. Other fields are untouched.
PATCH /users/42
{"role": "admin"}The failure mode worth naming explicitly: implementing PUT as if it were PATCH (silently ignoring omitted fields instead of resetting them) violates the contract clients expect from PUT, and a client that sends a partial body to a "PUT" endpoint expecting PATCH semantics will silently wipe out fields it didn't intend to touch. If partial updates are the common case, expose PATCH - don't repurpose PUT to behave like it.
Status Codes That Match What Actually Happened
POST /users
{"name": "Grace Hopper", "email": "grace@example.com"}
HTTP/1.1 201 Created
Location: /users/43
{"id": 43, "name": "Grace Hopper", "email": "grace@example.com"}
# --- deleting a resource with nothing meaningful to return ---
DELETE /users/43
HTTP/1.1 204 No Content- -201 Created: the request succeeded and a new resource was created. Include a Location header pointing at the new resource, and typically the created representation in the body.
- -204 No Content: the request succeeded but there is nothing meaningful to return - the standard response for a successful DELETE, or a PUT/PATCH where the client doesn't need the updated representation back.
- -200 OK: the generic success code - correct for GET, and for POST/PUT/PATCH when returning a body makes sense but the action wasn't specifically "created."
The Location header on a 201 response is easy to skip and genuinely useful: it tells the client exactly where to find (or next operate on) the resource it just created, without the client having to construct that URL itself from the response body.
A colleague's API returns `200 OK` for every single successful request, including creates and deletes. What would you push back on?
"That's fine - 200 means success, and all these requests did succeed."
"It's technically not wrong, but it throws away information the status code is supposed to carry - a client (or a monitoring dashboard) can't distinguish 'a new resource was created' from 'an existing one was fetched' just by the code. I'd use 201 with a Location header for creates and 204 for deletes, since that lets clients and tooling react correctly without parsing the response body just to figure out what kind of success this was."
What is the key semantic difference between PUT and PATCH?
Design The CRUD Master in the API Design Lab's REST Foundations act.