3 ms·

It's important to remember that aside from "convention" (and likely having a few helper functions defined in whatever server library you're using), there's noth

It's important to remember that aside from "convention" (and likely having a few helper functions defined in whatever server library you're using), there's nothing special about the method/verb in the HTTP protocol. You could literally define FOO and BAR methods in your API and use those if you found them useful. That said, PUT and PATCH can be quite useful if you're dealing with CRUD operations. If you want or need your API to be idempotent, use POST for creation and updating. If being idempotent isn't a requirement - or even a negative - then adhere to the convention: POST for creation and PUT/PATCH for update. PATCH is really nice to support when your objects are even moderately large or you want to reduce bandwidth costs. For example, let's say you have a user object in a NoSQL DB and each user is a JSON object with 100 keys. If you use POST or PUT to update, you're basically requiring that the user of your API... * Perform a GET to actually fetch the entire user object * POST/PUT the entire object back with the changes In addition, you're likely going to want the API to track the version of the object, otherwise you run into issues with multiple clients trying to update at the same time. This can be very problematic when updating the entire object. So you're basically wasting cycles on the server fetching data, wasting bandwidth for data that isn't going to be used at all, and possibly writing extra code to handle conflicts. With PATCH, you don't need to GET anything. You can update fields pretty easily w/o even knowing what's already there: PATCH /user/12345 { "age": 10 } Very little bandwidth is used. If you still need versioning along with that (yes, you do if this is more than a pet project) to resolve conflicts, then you can use a HEAD request for the user and return the version of the object in an HTTP header. Multiple patches from different versions can all be successfully applied on top of each other until a conflict arises. But, then you're getting into vector clocks or other solutions that are outside the scope of the question. Circling back, yes, PUT and PATCH can be very useful. ;) HTH

seph-reed 5y ago
I guess I'd expect PATCH /user/12345 { "age": 10 } and POST /user/12345 { "age": 10 } to be the same function for an API which doesn't allow users to assign ids. And thank you for your thorough answer.
wglass 5y ago
Agree with your sentiment, but I've always seen PUT as idempotent, not POST. Typical rest usage has POST creating new objects, and return the object with a new id. That's not idempotent. Doing it repeatedly makes new objects with new unique IDs. PUT is updating a given object, with the id in the URL. If you do it repeatedly, it's the same as a one time call. POST /user --> returns user with id PUT /user/12345 --> stores the data in the body for user with id 12345 PATCH /user/12345 --> merges the body with the existing object that has id 12345. (used to update specific field or fields)
- deleted 5y ago
  [deleted]
- dariusj18 5y ago
  That seems to muddle interface with implementation. What if your underlying architecture creates new versions of records when they are edited. That wouldn't be idempotent but you wouldn't change your API.
zests 5y ago
This comment makes me want to read a book about distributed systems.
jholman 5y ago
> If you want or need your API to be idempotent, use POST for creation and updating. This bit is wrong. First, implementing idempotence for your endpoint is UP TO YOU, no matter what method you use. For some methods (though not POST), idempotence is a requirement for spec compliance, not a thing HTTP somehow magically gives you. Second, although some methods (notably PUT and DELETE) are required to be idempotent (though that's really kind of a freebie when you read the rest of the requirements for those methods), you're welcome to implement idempotent endpoints behind a POST. > If you use POST or PUT to update... You're correct about PUT, but POST has no such requirement. You can send anything you want in a POST, because you may legally define whatever semantics you want on the fictitious purpose of the entity you're including. Circling back, PUT and PATCH give no advantages over POST. :)
iudqnolq 5y ago
> With PATCH, you don't need to GET anything. You can update fields pretty easily w/o even knowing what's already there: The concept of "patching" records and the http verb patch don't need to be linked. You could setup POST /user/12345/update to do what you described.

seph-reed 5y ago

I guess I'd expect PATCH /user/12345 { "age": 10 } and POST /user/12345 { "age": 10 } to be the same function for an API which doesn't allow users to assign ids. And thank you for your thorough answer.

wglass 5y ago

Agree with your sentiment, but I've always seen PUT as idempotent, not POST. Typical rest usage has POST creating new objects, and return the object with a new id. That's not idempotent. Doing it repeatedly makes new objects with new unique IDs. PUT is updating a given object, with the id in the URL. If you do it repeatedly, it's the same as a one time call. POST /user --> returns user with id PUT /user/12345 --> stores the data in the body for user with id 12345 PATCH /user/12345 --> merges the body with the existing object that has id 12345. (used to update specific field or fields)

deleted 5y ago
[deleted]
dariusj18 5y ago
That seems to muddle interface with implementation. What if your underlying architecture creates new versions of records when they are edited. That wouldn't be idempotent but you wouldn't change your API.

zests 5y ago

This comment makes me want to read a book about distributed systems.

jholman 5y ago

> If you want or need your API to be idempotent, use POST for creation and updating. This bit is wrong. First, implementing idempotence for your endpoint is UP TO YOU, no matter what method you use. For some methods (though not POST), idempotence is a requirement for spec compliance, not a thing HTTP somehow magically gives you. Second, although some methods (notably PUT and DELETE) are required to be idempotent (though that's really kind of a freebie when you read the rest of the requirements for those methods), you're welcome to implement idempotent endpoints behind a POST. > If you use POST or PUT to update... You're correct about PUT, but POST has no such requirement. You can send anything you want in a POST, because you may legally define whatever semantics you want on the fictitious purpose of the entity you're including. Circling back, PUT and PATCH give no advantages over POST. :)

iudqnolq 5y ago

> With PATCH, you don't need to GET anything. You can update fields pretty easily w/o even knowing what's already there: The concept of "patching" records and the http verb patch don't need to be linked. You could setup POST /user/12345/update to do what you described.