HTTP Methods PUT, PATCH, and DELETE in REST API Design

In this tutorial, you will learn about HTTP Methods PUT, PATCH, and DELETE in REST API ilink "Api Design" >}}. We cover key concepts, practical examples, and best practices to help you master this topic.

HTTP PUT replaces an entire resource, PATCH applies a partial modification, and DELETE removes a resource, each with distinct idempotency guarantees and status code conventions.

flowchart TD
  A[Client] -->|PUT /users/42| B[Full Replacement]
  A -->|PATCH /users/42| C[Partial Update]
  A -->|DELETE /users/42| D[Removal]
  B -->|200 OK| A
  C -->|200 OK| A
  D -->|204 No Content| A
  style A fill:#e1f5fe
  style B fill:#fff9c4
  style C fill:#c8e6c9
  style D fill:#ffcdd2

PUT replaces the entire resource at the given URI. Think of it like rewriting a whole page in a notebook. You erase everything and write new content from scratch. If you send a PUT with only the name field, you will overwrite all other fields with empty or default values.

PATCH applies a partial update. Think of it like using correction fluid on a single word in a notebook. The rest of the page stays exactly as it was. You only send the fields you want to change.

DELETE removes the resource. Think of it like tearing out a page entirely. Once deleted, GET returns 404 or 410.

PUT and DELETE are idempotent. Calling PUT /users/42 with the same body 10 times is the same as calling it once. Calling DELETE /users/42 10 times has the same effect as calling it once (the resource is gone after the first call). PATCH is not necessarily idempotent, though many implementations make it so.

Example: PUT (Full Replacement)

import requests

# Original resource: {"id": 42, "name": "Alice", "email": "alice@example.com", "role": "admin"}
# PUT replaces the entire resource
updated_user = {
    "name": "Alice Smith",
    "email": "alice.smith@example.com",
    "role": "editor"
}
response = requests.put(
    "https://api.example.com/users/42",
    json=updated_user
)
print(f"Status: {response.status_code}")
print(f"Updated: {response.json()}")

Expected output:

Status: 200
Updated: {"id": 42, "name": "Alice Smith", "email": "alice.smith@example.com", "role": "editor"}

Example: PATCH (Partial Update)

import requests

# Only update the email field, leave everything else unchanged
patch_data = {"email": "alice.new@example.com"}
response = requests.patch(
    "https://api.example.com/users/42",
    json=patch_data
)
print(f"Status: {response.status_code}")
print(f"Partially updated: {response.json()}")

Expected output:

Status: 200
Partially updated: {"id": 42, "name": "Alice", "email": "alice.new@example.com", "role": "admin"}

Example: DELETE

import requests

response = requests.delete("https://api.example.com/users/42")
print(f"Status: {response.status_code}")
# Verify deletion
get_response = requests.get("https://api.example.com/users/42")
print(f"GET after DELETE: {get_response.status_code}")

Expected output:

Status: 204
GET after DELETE: 404

Common Mistakes

1. Using PUT like PATCH — Sending only a few fields with PUT will delete the fields you did not include. PUT replaces the whole resource.
2. Not returning 204 on DELETE — DELETE should return 204 No Content, not 200 OK with a body. The resource is gone so there is nothing to return.
3. Making PATCH not idempotent when it should be — PATCH is technically non-idempotent but in practice, making it idempotent (applying the same patch twice is the same as once) is safer.
4. Returning 200 on successful DELETE — Return 204. If you return 200, clients may try to parse a body that does not exist.
5. Not handling DELETE on already-deleted resources — Return 404 or 410 if the resource does not exist, not 204 or 200.

Practice Questions

1. What is the difference between PUT and PATCH?
2. Why is DELETE idempotent?
3. What status code should a successful DELETE return?
4. What happens if you PUT a resource with missing fields?
5. Challenge: Write a script that creates a user with POST, retrieves it with GET, updates the email with PATCH, replaces the entire user with PUT, and deletes with DELETE. Print the state after each operation.

FAQ

Mini Project

Design and implement a simple REST client in Python that performs CRUD operations on user resources. Use all five major HTTP methods (GET, POST, PUT, PATCH, DELETE) against a mock API. Track and display the state changes after each operation.

What's Next

Now learn about idempotency in REST API Design.