PUT, PATCH, and DELETE

Changing and removing things

We can read data with GET and create data with POST. But once something exists, we need ways to change it and remove it. That is where PUT, PATCH, and DELETE come in.

PUT: replace the whole thing

PUT replaces a resource entirely. You send the complete new version of the resource, and whatever was there before gets overwritten.

PUT /books/book-1 HTTP/1.1
Content-Type: application/json

{"title":"The Left Hand of Darkness","author_id":"author-1","genre":"science-fiction","description":"A novel about gender"}

Here is the critical thing about PUT: if book-1 previously had a published_at field and you did not include it in this request, that field is gone. PUT means “here is the new version, replace everything.” Any fields you leave out get removed.

PUT is idempotent. Sending the exact same PUT request twice produces the same result. After the first call, book-1 has the new data. After the second call, book-1 has… the exact same data. Nothing changed. Compare this to POST, where sending the same request twice creates two different resources.

PATCH: change just part of it

Sometimes you do not want to replace the whole resource. You just want to update one or two fields. That is PATCH.

PATCH /books/book-1 HTTP/1.1
Content-Type: application/json

{"description":"A groundbreaking novel about gender and society"}

Only the description field gets updated. Everything else (title, author_id, genre, published_at) stays exactly as it was. PATCH is like saying “change just these fields and leave the rest alone.”

What do you think happens if you send that same body as a PUT instead of a PATCH? The description would be set, but every other field would be removed. You would end up with a book that only has a description and nothing else. That is the key difference between PUT and PATCH, and getting them confused can cause real data loss.

[!NOTE] The REST API Design course covers PUT vs PATCH in depth, including when to prefer one over the other and how to handle missing fields safely.

DELETE: remove it

DELETE removes a resource. Simple as that.

DELETE /books/book-1 HTTP/1.1
Host: api.example.com

HTTP/1.1 204 No Content

The server deletes the resource and responds with 204 No Content. That status code means “it worked, but I have nothing to send back.” The book is gone, so there is no data to return. Some APIs return 200 OK with the deleted resource in the body instead, but 204 is more common for deletions.

DELETE is idempotent. Deleting book-1 once removes it. Deleting book-1 again does nothing, because it is already gone. Either way, the result is the same: book-1 does not exist. (Some servers return 404 on the second attempt, others return 204. Both are valid.)

How they all fit together

*PATCH is technically non-idempotent because its effect depends on the current state of the resource, but in practice it is often designed to be idempotent.

Take a moment to notice the pattern. GET and HEAD are the safe, read-only methods. POST creates and is the only common method that is neither safe nor idempotent. PUT and DELETE are not safe (they modify data), but they are idempotent (doing them twice has the same result).

There is one more method we need to cover: OPTIONS. It does something completely different from the rest, and it plays a critical role in cross-origin requests. That is the next lesson.

Exercises

Exercise 1: Create a resource with POST. Update it with PUT (send the full replacement). Then update one field with PATCH. Compare the results.

Exercise 2: Send the same PUT request twice. Verify the resource looks the same after both calls. That is idempotency.

Exercise 3: Delete a resource. Try deleting it again. Note the status code you get the second time (404 or 204, depending on the API).