PUT vs PATCH: REST API Updates and Idempotency Explained

Previously in this course, we covered the foundational introduction to HTTP methods and explored the specific semantics of GET and POST requests. Now that you understand how to create and retrieve resources, you need to know how to modify them.

In real-world applications, data is rarely static. You will constantly need to change task descriptions, update user profiles, or toggle status flags. This is where the confusion between PUT and PATCH usually begins.

Understanding Idempotency in REST

Before comparing the methods, we must define idempotency. An operation is idempotent if performing it multiple times yields the same result as performing it once.

If you send a request to set status to "completed", the state of the server after one request should be identical to the state after ten identical requests. Idempotency is a safety guarantee; it ensures that network retries or accidental double-clicks don't corrupt your data.

PUT: The Replacement Strategy

The PUT method is designed for replacement. When a client sends a PUT request, it is telling the server: "This is what the resource should look like from now on."

If your resource is a Task with fields title and completed, a PUT request must contain the entire object. If you omit a field, the server should logically set that field to a default value or null, because you are replacing the previous state entirely.

Worked Example: PUT

Imagine a task with ID 123. Current state: {"title": "Buy milk", "completed": false}

Request: PUT /tasks/123 Body: {"title": "Buy oat milk"}

Result: The server replaces the old object with the new one. The completed field is now lost or set to null, because the client did not provide it.

PATCH: The Partial Update

The PATCH method is designed for partial modification. It tells the server: "Apply these specific changes to the existing resource."

PATCH is more efficient for clients with limited bandwidth or when you only want to update a single property without fetching the entire object first. Because PATCH only modifies specific fields, it is inherently non-idempotent in many implementations (e.g., an "increment" operation), though it can be implemented idempotently depending on the payload format.

Worked Example: PATCH

Current state: {"title": "Buy milk", "completed": false}

Request: PATCH /tasks/123 Body: {"completed": true}

Result: The server keeps the original title and only updates completed to true. New state: {"title": "Buy milk", "completed": true}

Hands-on Exercise

In our ongoing Task Manager project, we need to allow users to mark tasks as done.

1. Draft the logic: Create a pseudo-code function that handles a PATCH request for a task.
2. Verify: If a user sends a PATCH request with {"completed": true} to /tasks/101, ensure your code merges this with the existing record rather than overwriting the entire object.
3. Reflect: If you were to use PUT for this same operation, what data would the client be forced to send?

Common Pitfalls

• Partial Updates via PUT: A common mistake is using PUT to perform partial updates. While it might "work," it violates the REST contract. Clients expecting a full replacement will be surprised when fields aren't reset.
• Ignoring Idempotency: If your PATCH operation performs an action like "add 1 to the view count," it is not idempotent. If a user clicks twice, the count goes up by 2. Always design your API to handle these cases, perhaps by using Redis idempotency patterns if the operation is sensitive.
• Assuming PATCH is always safe: Because PATCH can involve complex logic, ensure your server-side validation is robust. You aren't replacing the object, so you must ensure the partial data remains valid within the existing schema.

FAQ

Q: Should I always implement both? A: Not necessarily. If your resources are small, PUT is often sufficient and easier to reason about. Only add PATCH when your resources grow large enough that sending the full object becomes a performance burden.

Q: Is PATCH always non-idempotent? A: Not always. If your PATCH payload is a simple key-value set (e.g., {"status": "active"}), it is technically idempotent. However, the HTTP spec does not mandate it, unlike PUT.

Recap

You now know that PUT is for full replacement (and is idempotent), while PATCH is for targeted, partial updates. Using these correctly makes your API predictable and easier for client developers to integrate. As we advance our project, we will rely on these methods to manage the lifecycle of our tasks.

Up next: Understanding DELETE — how to safely remove resources from your system.