restful apis: put vs. patch



~2 min read


294 words

I routinely find myself looking up the differences between the HTTP methods (aka verbs) PUT and PATCH. While there’s plenty of nuance, some of which I’ll get to below, the tl;dr is:

PATCH and PUT have different semantics. PUT means create/replace and it is idempotent. PATCH means update (full or partial) and it is not idempotent.1

The Wikipedia article on HTTP has a great table which summarizes several of the HTTP methods - I’ve adapted it lightly below: 2.

HTTP method RFC Request has Body Response has Body Safe Idempotent Cacheable
DELETE RFC 7231 Optional Yes No Yes No
GET RFC 7231 Optional Yes Yes Yes Yes
POST RFC 7231 Yes Yes No No Yes
PUT RFC 7231 Yes Yes No Yes No
PATCH RFC 5789 Yes Yes No No No

While William Durand may object, I like how simple PATCH makes it to update a record: Instead of having to GET the record’s most recent data so that you can replace the entire record with a PUT, with PATCH, you can just declare what you’d like set. 3

For example - update user 123 the body can be as simple as:

PATCH /users/123

{ "email": "" }

Related: Idempotence


Hi there and thanks for reading! My name's Stephen. I live in Chicago with my wife, Kate, and dog, Finn. Want more? See about and get in touch!