May 20th, 2016
Here's a question we hear often:
To update an existing resource, when should I use
PUT and when should I use
PATCH has several distinct advantages over
PUT when it comes to updating things:
PUTrequires sending the entire object, hence a larger payload over the network. With
PATCH, if you only want to change one or a few fields, you only need to send those fields.
PUTrequires that you first do a GET. With
PATCH, all you need is the object's ID, and you can often avoid the extra API call.
PUTcan have unintended side-effects related to properties you don't want to change. For example, some properties have default values, often inherited from some parent object, that can be overwritten. When you do a GET on such a resource, you'll get the default if it hasn't been overwritten. If you then change some other property and do a
PUT, you're unintentionally overriding the inherited value with an explicit one. Now if the default value on the parent changes, that change won't flow to the child as expected.
PUT. For example, suppose user A wants to modify a product's quantity multiplier while user B wants to modify the same product's description. Both users have done a GET and have the product's JSON representation and modify it. If user A
PUTs their change first, then user B will inadvertently revert the quantity multiplier change when they send their
PATCH, user A can send only the quantity multiplier change and user B can send just the updated description, and they are at no risk of a conflict.
All these warnings of great peril beg the question: When should you use
These are the situations where using
PUT makes sense:
POST when you want the ID to be auto-generated by the platform, i.e. you want us to decide where to "put" it.)
PUTis often the only verb available for writing to such endpoints.
PUT actually has a few nice qualities when used in the above scenarios:
PUTis idempotent, i.e. you shouldn't need to check if it has already been called, because calling it a second time will leave the resource in exactly the same state as calling it the first time. (
POST, on the other hand, generally creates a new resource with each successive call.)
PUTthe assignment and it will either create a new one or overwrite the existing one.
|Use ||Use ||Use |
|- You want to create a new resource where WE (the platform) are generating the ID. The new ID will be returned in the response body (as part of the full object), and the URI of the new resource will be returned in the Location response header.||- You want to create a new resource where YOU are providing the ID, use ||- You want to update an existing resource.|
|- You want to completely replace a resource with another (same ID), use ||- You want to "move" a resource. The old ID goes in the URI; the new one in the request body.|