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
- -Follow one resource through its whole life and name the response at each step
- -Handle the cases beyond the happy path: null in a PATCH, 202, 409, 422 and 410
Tip: the highlighter is on - just select any text below to mark it. Use the highlighter button up top to change color or turn it off. Highlights are saved on this device only. Log in to save them to your account instead.
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.
Following One Resource Through Its Life
The quickest way to remember the details is to follow a single user from birth to deletion, and note the right answer at each step:
- -POST /users with a name and email: 201 Created, a Location header of /users/43, and the new user in the body.
- -GET /users/43: 200 OK with the user.
- -PATCH /users/43 with {"role": "admin"}: 200 OK with the updated user (or 204 No Content if the client does not need it). Only the role changes.
- -PUT /users/43 with a complete user: 200 OK. Anything left out of the body is cleared.
- -DELETE /users/43: 204 No Content.
- -GET /users/43 again: 404 Not Found, or 410 Gone if you want to say that it existed once and was deliberately removed.
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.
There is one subtle point about PATCH. In the common JSON Merge Patch format, a field you send replaces the stored value, a field you omit is left alone, and a field you send as null is removed. So {"phone": null} deletes the phone number, while {} changes nothing. Decide this rule once, write it down, and apply it consistently.
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."
Beyond the Happy Path
- -202 Accepted: the request was understood but the work will finish later, such as a long report. Return a way to check on its progress.
- -409 Conflict: the request is valid but clashes with the current state, for example creating a user with an email that already exists.
- -422 Unprocessable Content (or 400): the request is well-formed but fails validation, such as an email with no at-sign. Say which field and why.
- -410 Gone: the resource existed and has been permanently removed, which can help clients and crawlers stop asking.
Finally, think about repeats. GET, PUT and DELETE can be sent twice with the same result, which is what makes them safe to retry after a timeout. POST is not, because repeating it can create a second resource, so give creating endpoints an idempotency key, as the Idempotency chapter in the HLD course explains.
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.
Discussion0
Join the Discussion
Sign in to leave comments, reply to others, or like insights.
No comments yet. Be the first to start the thread!