CODEWITHSUNDEEP
resthttppostroutesput
Alex Rothberg
Alex Rothberg

Reputation: 10993

REST PUT vs POST with UUID

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

Upvotes: 9

Views: 7728

Answers (3)

Pankaj Jangid
Pankaj Jangid

Reputation: 612

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.

Upvotes: 1

nikita
nikita

Reputation: 2817

The main difference between POST and PUT:

POST is used to append new entities. POST is not idempotent. That means if you send POST request ten times you'll create ten different entities. Usually you should get 201(Created) response code to POST request coupled with Location header pointing to URL of newly created resource. In your case I suggest to POST to URL sthm like 

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

Response:

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

PUT request is used to modify existing state. PUT is idempotent. Usually you'll get 200(OK) response code.

You need to contain UUID in PUT/POST payload. UUID is part of representation of your resource. PUT and POST both transfer representation to REST server in order to change/append resource state.

BTW you should't use URI term in REST. URI is sthm that may not has representation, though URL always has representation.

Upvotes: -1

Eric
Eric

Reputation: 1701

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.

Upvotes: 4

Related Questions