Can a PATCH Create a Resource?

No, the HTTP PATCH method is specifically designed for partially updating existing resources, not creating new ones. Its primary purpose is to apply partial modifications to a resource, sending only the changes rather than the complete resource representation.

Understanding the Purpose of HTTP PATCH

The PATCH method is a non-idempotent HTTP method used to apply partial modifications to an existing resource. This means you send a set of instructions describing how to modify a resource, and the server applies those changes. It's particularly useful when you only need to update a small portion of a large resource, saving bandwidth and processing power compared to sending the entire updated resource.

For example, if you have a user profile with many fields (name, email, address, phone, preferences, etc.) and you only want to change the user's email address, a PATCH request allows you to send just the new email value. The server then applies this specific change to the existing user record.

Why PATCH Is Not for Resource Creation

The fundamental semantic difference lies in their intent:

• PATCH: Intends to modify an existing resource at a known URI.
• POST: Intends to create a new resource or submit data for processing, often returning a new URI.
• PUT: Intends to replace an existing resource entirely or create a resource if it doesn't exist at a specific URI (making it idempotent).

If a PATCH request is sent to a URI where no resource currently exists, the server would typically respond with a 404 Not Found status code, as there is no resource to partially update. Some sophisticated implementations might handle it differently, but the standard behavior and intended use do not include creation.

Distinguishing PATCH from POST and PUT

To clarify the distinct roles of these HTTP methods, let's compare them:

HTTP Method	Primary Purpose	Idempotent?	Typical Status Codes (Success)	Common Use Cases
POST	Create new resources or submit data for processing.	No	201 Created, 200 OK	Submitting a form, uploading a file, adding an item to a collection (e.g., adding a product to a shopping cart).
PUT	Replace an existing resource or create if it doesn't exist at the given URI.	Yes	200 OK, 204 No Content, 201 Created	Updating all fields of a user profile, replacing an entire document, creating a resource at a client-specified URI.
PATCH	Partially update an existing resource.	No	200 OK, 204 No Content	Changing a user's email, updating the status of an order, incrementing a counter, toggling a boolean flag.

• Idempotency: An operation is idempotent if applying it multiple times has the same effect as applying it once. PUT is idempotent because sending the same request multiple times will result in the same resource state. POST and PATCH are generally not idempotent, as repeated requests could lead to different results (e.g., creating multiple resources with POST, or applying a partial update to an already updated state with PATCH).

When to Use Each Method

• Use POST when you need to create a new resource, and the server determines the new resource's URI (e.g., adding a new blog post).
• Use PUT when you want to replace an entire resource at a known URI, or create a resource if you specify its exact URI (e.g., updating all details of a specific book, or creating a file at /documents/report.pdf).
• Use PATCH when you only need to modify specific fields of an existing resource, rather than replacing the entire resource (e.g., updating only a user's password).

Practical Insights and Examples

Consider an API for managing tasks:

• Creating a new task:

  • POST /tasks with a request body like { "title": "Buy groceries", "status": "pending" }.
  • Response: 201 Created with the new task's URI and details.

• Updating an entire task:

  • PUT /tasks/123 with a request body like { "title": "Buy milk and eggs", "status": "completed", "dueDate": "2023-12-31" }.
  • This replaces the entire task 123 with the provided data. Any fields not included would be removed or reset.

• Partially updating a task:

  • PATCH /tasks/123 with a request body like { "status": "completed" }.
  • This only changes the status field of task 123, leaving title and dueDate untouched. This is the sole purpose of PATCH.

For further details on HTTP methods and their specifications, you can refer to the MDN Web Docs on HTTP methods and RFC 5789 for the PATCH method.

In summary, while HTTP offers various methods for interacting with resources, PATCH is strictly for modifying existing ones, never for their initial creation.