REST PUT vs POST with UUID

Question

If I use a UUID to identify an object as part of my URI of my REST endpoint:

 /entities/<uuid>/ 

and that the UUID generated by the client when creating new objects, is there a best practice for using PUT vs POST ? In other words, the UUID is created by the client, not the server.

If I were using PUT , is the message payload expected to also contain a UUID ? In this case, both the message and the URIs that identify the object will contain the UUID .

For specification see: REST RFC

Answer 1

Since you (the client) already know the UUID, I would say that PUT is the best practice, and you do not need to include the UUID in the payload. Admittedly, PUT vs POST somewhat controversial, and reading and re-reading the RFC does not fully clarify this for me. But I think the previous is orthodoxy.

Check out PUT vs POST in REST for a nice discussion.

Answer 2

Understand the difference between PUT and POST.

PUT is intended to replace the resource ( http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.6 ) that the URI points to with a new one. And this is idempotent, i.e. How many times you call it with the same payload, the result is the same; it will make the same resource available through the URI.

So, if there is no resource, a new one is already being created. Even in this case, the result will be the same, that is, it will make the same resource available through the URI.

POST means creating a sub-resource ( http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5 ) to the resource pointed to by the URI. If the resource is a list, it will add an element to it. If this is an element, then it should add something to the element, maybe an attribute.

So, ideally, if the element that the URI points to is not available, then this should be an error condition. Maybe 404. POST is an addition to an existing resource.

Coming to your question, it is better to use POST with "/ entity /" as a URI as described above. You must not use a non-existent resource UUID in a URI with a POST method. If you use PUT, use "/ entities /".

 POST /entities/ HTTP/1.1 Content-Type: application/json { UUID: <UUID>.. OtherStuff: ... } PUT /entities/<UUID> HTTP/1.1 Content-Type: application/json { UUID: <UUID>.. OtherStuff: ... } 

The answer should be the same

 HTTP/1.1 201 Created Location: http://www.examples.com/entities/<uuid>/ 

although PUT is idempotent, but if the PUT method is used again, then it should use a 200 or 204 response.

Second question: ideally, complete resource information should be in the PUT payload, and not just in the URI.

Answer 3

The main difference between POST and PUT:

POST is used to add new objects. POST is not idempotent . This means that if you send a POST request ten times, you will create ten different objects. Usually, you should get a 201 (Created) response code for the POST request along with a Location header pointing to the URL of the newly created resource. In your case, I suggest POST at sthm url like

 POST /entities/ HTTP/1.1 Content-Type: application/json { UUID: <UUID>.. OtherStuff: ... } 

Answer:

 HTTP/1.1 201 Created Location: http://www.myREST/entities/<uuid>/ 

A PUT request is used to change an existing state. Put idempotent . You will usually get a 200 response code (OK).

You must contain the UUID in the PUT / POST payload. UUID is part of the representation of your resource. PUT and POST send the view to the REST server to change / add the state of the resource.

By the way, you should use the term URI in REST. A URI is a sthm that may not have a view, although a URL always has a view.