Question

I have the following URI: Posts/{postId}/Comments/{commentId}
I would like to enable users to edit a comment through my API, should the edit be done with POST or PUT?
One one hand, POST updates the contents of a resource so that makes sense but on the other hand PUT replaces it with a new one. So if I understand correctly with POST I need to send only what needs to be updates and with PUT I send the whole resource.
Usually in edit forms, the whole resource is loaded anyway so what’s the point of using POST?
If I take one approach or the other, what are the differences?

Answer 1

From what I have read (in RESTful Web Services, published by O’Reilly), it seems clear that you should use PUT to update an existing comment.

• PUT is meant to be used for updating as well as creating a resource.

• POST can also be used for creating a resource. The difference here is that when POSTing, you don’t need to know the exact URI of the resource to be created. (The service will report the new resource’s URI in its response.)

• POST is appropriate for partial updates, or when appending information to a resource; PUT is appropriate for a full update (replacement) of a resource.

• When updating, you can send partial updates, but you should make sure that these are idempotent; ie. if you send the same update more than once, the update will always have the same effect. Don’t send an update such as “Increase n by 1″; instead, send an update such as “Set n to 5.”

Thus, my suggestion for your case are as follows:

• Use POST to /Posts/{postId}/Comments to create a new comment, since the client doesn’t know the {commentId} in advance.

• Use PUT /Posts/{postId}/Comments/{commentId} to completely update a comment (or perhaps POST when appending text to it).