PUT vs. PATCH Requests Explained

Resource updating is a core operation when building RESTful APIs. Two HTTP methods often used for updates are PUT and PATCH. Although they may seem similar, they differ in the scope of updates, the expected request body contents, server-side semantics, and usage patterns. Choosing the right one improves API clarity, performance, and client experience.

This article explains both methods in detail, compares them across key factors, and shows examples to help you decide when to use each.

PUT vs. PATCH Request: Overview

A PUT request is an operation that creates or replaces a resource at a specific URI. The client sends a complete representation of the resource, and the server stores that representation as the new state. If the resource already exists, PUT replaces it. If the resource does not exist, some servers may allow PUT to create it, but this behavior is implementation-dependent and not guaranteed by the HTTP specification.

A PATCH request, by contrast, is an operation that partially modifies an existing resource. Instead of sending the entire resource, the client sends a set of changes to the current state. PATCH is typically applied to existing resources. While not explicitly forbidden by the specification, most APIs require the resource to already exist.

The key difference in definition is replacement versus modification. PUT describes what the resource should look like, while PATCH describes how the resource should change.

The table below provides a structured comparison between the two:

PUT vs. PATCH Request: In-Depth Comparison

This section examines PUT and PATCH in detail across all major comparison factors. Each subsection explains not only what the difference is, but why it matters when designing or consuming APIs.

Purpose

The primary purpose of PUT is to establish a complete and authoritative state for a resource. When a client issues a PUT request, it assumes responsibility for the entire resource representation. This makes PUT well-suited for scenarios where the client fully owns the data model or regularly syncs complete objects.

The following diagram illustrates a PUT request:

PATCH exists to support incremental updates. Its purpose is to allow clients to modify specific parts of a resource without needing to understand or transmit the entire structure. This is especially useful when resources are large, frequently updated, or partially editable by different clients.

The following diagram illustrates a PATCH request:

In practice, PUT emphasizes state replacement, while PATCH emphasizes state evolution.

Request Body Contents

A PUT request body should contain a full representation of the resource. This includes all required fields and any optional fields the client wants to preserve. Omitting fields is often interpreted as intentional removal or reset, depending on the server's implementation.

A PATCH request body contains only the fields that should change. Fields not included in the payload are left untouched. The body structure may vary depending on implementation, ranging from simple JSON objects to standardized patch formats such as JSON Merge Patch or JSON Patch.

This difference has practical consequences. With PUT, clients must carefully include all fields to avoid accidental data loss. With PATCH, clients can safely update individual attributes without needing a full resource context.

Effect on Resource

Because PUT replaces the resource, its effect is global. The server treats the request body as the new canonical version of the resource. Any existing values not represented in the request may be removed or reset.

PATCH has a localized effect. It modifies only the fields specified in the request body. All other fields remain unchanged from before the request.

This distinction is critical when dealing with complex or shared resources. PUT can unintentionally overwrite changes made by other clients, while PATCH minimizes the risk of unintended side effects.

Idempotency

Idempotency means an operation can run multiple times without changing the result beyond the first execution, producing the same outcome each time.

PUT is idempotent by definition. Sending the same PUT request multiple times results in the same final resource state. This makes PUT reliable when requests may be retried due to network failures or timeouts.

PATCH is not inherently idempotent. The effect of repeating a PATCH request depends on how the server interprets the changes. For example, a PATCH that increments a value may produce different results when applied multiple times.

Use Cases

Use PUT when:

• The client has a complete resource representation.
• The update should fully replace existing data.
• Predictable retry behavior is required.
• The API supports "upsert" semantics (a combination of INSERT and UPDATE).

PATCH is the best choice when:

• Only a small subset of fields needs updating.
• Payload size should be minimized.
• Multiple clients may modify different parts of the same resource.
• Partial edits are more common than full replacements.

Choosing the correct method improves API clarity and prevents misuse.

Examples

A typical PUT example updates an entire resource. For example:

PUT /users/123
Content-Type: application/json

{
  "id": 123,
  "name": "Ana",
  "email": "[email protected]",
  "age": 30
}

This request replaces the existing user resource with the provided data. Any missing fields may be removed.

A typical PATCH example updates a single field. For example:

PATCH /users/123
Content-Type: application/json

{
  "email": "[email protected]"
}

This request updates only the email field, leaving all other fields unchanged.

These two examples illustrate the core philosophical difference - PUT defines the whole, while PATCH defines the change.

Conclusion

This article explained the difference between PUT and PATCH requests and when to use each. Understanding how HTTP methods work in practice helps you design, test, and troubleshoot APIs more effectively. By knowing when and how requests are processed, you can build systems that are predictable, reliable, and easier to maintain.

Next, check out our cURL POST requests guide or learn how to show and send HTTP headers with cURL.