Skip to content

PUT vs PATCH in REST APIs

In [[RESTful API]] design, both PUT and PATCH are HTTP methods used to update existing resources on the server.^[600-developer__principle__restful-rule.md] However, they differ significantly in how they handle the update process and the amount of data required from the client.

Core Distinction

The primary difference lies in the scope of the update: PUT is used to update a resource with a complete set of data, whereas PATCH is used to update a resource with partial changes^[600-developer__principle__restful-rule.md].

  • PUT: The client provides the complete resource data.^[600-developer__principle__restful-rule.md]
  • PATCH: The client provides only the specific attributes that need to be changed.^[600-developer__principle__restful-rule.md]

Semantic Properties

Both PUT and PATCH requests are considered idempotent, meaning that making the same request multiple times produces the same result on the server state^[600-developer__principle__restful-rule.md].

Idempotency

  • PUT: Since PUT updates a resource based on a complete payload, sending the same request multiple times will result in the same final state^[600-developer__principle__restful-rule.md].
  • PATCH: While often used for partial updates, PATCH is also classified as idempotent in standard RESTful definitions^[600-developer__principle__restful-rule.md].

Common Usage Examples

In a standard RESTful architecture (e.g., /api/zoos), the methods are applied as follows^[600-developer__principle__restful-rule.md]:

  • PUT /zoos/ID: Updates the specified zoo. The request body must contain the full information for that zoo^[600-developer__principle__restful-rule.md].
  • PATCH /zoos/ID: Updates the specified zoo. The request body contains only the changed properties (partial information)^[600-developer__principle__restful-rule.md].

Response Codes

When a PUT or PATCH operation successfully creates or modifies data, the standard HTTP status code returned is 201 CREATED^[600-developer__principle__restful-rule.md]. If there are validation errors during the update attempt (e.g., malformed data), the server should return a 422 Unprocesable entity status code^[600-developer__principle__restful-rule.md].

Sources

^[600-developer__principle__restful-rule.md]