In REST is POST or PUT best suited for upsert operation?
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://www.rfc-editor.org/rfc/rfc5789
This is extremely fine tuning.
According to MDN Web Docs :
PUT
The HTTP PUT request method creates a new resource or replaces a representation of the target resource with the request payload.
The difference between PUT and POST is that PUT is idempotent: calling
it once or several times successively has the same effect (that is no
side effect), whereas successive identical POST requests may have
additional effects, akin to placing an order several times.
Syntax
PUT /new.html HTTP/1.1
Example
Request
PUT /new.html HTTP/1.1
Host: example.com
Content-type: text/html
Content-length: 16
<p>New File</p>
Responses
If the target resource does not have a current representation and the
PUT request successfully creates one, then the origin server must
inform the user agent by sending a 201 (Created) response.
HTTP/1.1 201 Created
Content-Location: /new.html
If the target resource does have a current representation and that
representation is successfully modified in accordance with the state
of the enclosed representation, then the origin server must send
either a 200 (OK) or a 204 (No Content) response to
indicate successful completion of the request.
HTTP/1.1 204 No Content
Content-Location: /existing.html
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
- 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;
- Deleting each of those keys by sending a DELETE to http://www.somewhere.com/resources/k1;
- 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.