In REST is POST or PUT best suited for upsert operation?

Question

I keep a key-value storage in the server for the client. If the user sends key "k1", then I upsert it to the database. Is this considered POST or PUT?

Also I have another operation that removes all existing keys and adds the new key. Is this POST or PUT because it clears records and adds a new one.

Answer 1

If the user send key "k1" then I upsert it to the database. Is this considered POST or PUT.

According to the HTTP specification:

The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server. If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI.

I therefore think that the use of PUT for an insert or update is perfectly legitimate, provided that in both cases the URI is known in advance. If you're using the key as part of the URI (as k1 in http://www.somewhere.com/resources/k1) this should be the case. To be ideally RESTful, however, a GET to the same URL should also allow you to download the resource.

Also I have another operation which remove all existing keys and add the new key, is this POST or PUT because it clear records and add new one.

I don't think this operation could be considered RESTful because it does two things. It seems to be providing a macro to satisfy the needs of a particular client, rather than simple access to data. A standard RESTful design would be

1. Getting a list of keys by sending a GET to the parent URL. In the example above, that would be http://www.somewhere.com/resources;
2. Deleting each of those keys by sending a DELETE to http://www.somewhere.com/resources/k1;
3. Adding the replacement by sending a PUT to http://www.somewhere.com/resources/k2.

It's less clear cut, but I think it would also be legitimate to delete all resources by sending a single DELETE request to http://www.somewhere.com/resources.

Answer 2

The idea behind upsert operation is that clients have information about/decide on data structure and sending data with key value. So request model for upsert operation is very similar to update operation with key included as the example below:

/customers/jimmy

The expected method for updating an existing record is PUT. So your choice should be PUT.

POST is generally used for inserting a new record with a brand new content like in the example below:

POST /customers HTTP/1.1
Content-Type: ...
Content-Length: ...
Host: server.yourdomain.com
Accept: ...
User-Agent: ...

id      jimmy
name    jimmy
Occupation   Stackoverflower

So in your case you do not need any POST operation because PUT for upsert operation also covers that.

Here the critical question about upsert is how likely you trust your client about upsert operation. If a client desires to insert a new record with an existing key what happens? In your case you should handle this request as an update because both insert and update requests come to the same api and you have an existing record. This is the question to be answered on your side about design.

Answer 3

Polly Shaw's answer is correct, but I would like to mention that given that the message might very likely be incomplete (missing the ID when the resource is not yet created), a PATCH verb would be slightly more correct.

https://tools.ietf.org/html/rfc5789

This is extremely fine tuning.

Answer 4

If you mix everything, you're probably not doing REST. From RESTful Web services: The basics POST and PUT have distinct usage scenario:

To create a resource on the server, use POST.
To retrieve a resource, use GET.
To change the state of a resource or to update it, use PUT.
To remove or delete a resource, use DELETE.

So consider POST as posting a new ticket to a blog and PUT to change an existing value.

Removing should be done as a distinctive operation with the DELETE verb. As "remove all" before update doesn't sound like a good idea.