REST PUT vs POST with UUID

Question

If I am using a UUID to identify the entity as part of my URI of my REST endpoint:

/entities/<uuid>/

and that UUID is generated by the client when creating new entities, is there a best practice as far as using PUT vs POST? In other words the UUID is generated by the client as opposed to by the server.

If I were to use PUT, is it expected that the message payload contain the UUID as well? In this case the both the message as well as the URI identifying the entity would contain the UUID.

For spec, see: the REST RFC

Answer 1

Since you (the client) already know the UUID, I would say PUT is the best practice, and you don't need to include UUID in the payload. Admittedly, PUT vs POST is somewhat controversial and reading and re-reading the RFC doesn't totally clear it up for me. But I think the preceding is orthodoxy.

See PUT vs POST in REST for a nice discussion.

Answer 2

Understand the difference between PUT and POST.

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

So, if the resource is not there already a new one is created. Even in this case the result is same i.e. it will make the same resource available through the URI.

POST is meant create 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 then it will add an item to it. If it is item then it should add something to the item, an attribute may be.

So, ideally if the item pointed to by the URI is not available then it should be an error condition. May be a “404”. POST is all about adding to an existing resource.

Coming to your question, it is best to use POST with “/entities/“ as URI as per the description above. You should not use a non-existent resource UUID in the URI with POST method. If you are using PUT then 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: ...
}

Response should be 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 200 or 204 in response.

Your second question: ideally the full resource detail should be in the PUT payload instead of just URI.