Restful URLs with data in query string or request body?

Based on HTTP's definition of PUT, your first request is overwriting the list of players with a new list that contains just one player name. It is not adding to the list of players.

Based on HTTP's definition of PUT, your first request is overwriting the list of players with a new list that contains just one player name. It is not adding to the list of players. The second option does not really make much sense to me.

Doing PUT without a body is not really consistent with the meaning of PUT. Considering that one of the standard definitions of POST is to append to an existing resource, I'm not sure why you wouldn't do POST /players { "name": Gretzky } If you are sure that all you player names are going to be unique then you could use PUT like this: PUT /player/Gretzky { "name": Gretzky } When you decide to do REST on HTTP you are agreeing to use HTTP in the way that is defined in RFC2616. That's what the uniform interface constraint means.

And just to be pedantic, there is no such thing as a REST URL and you can't test either option in a browser because without javascript, you can't do a PUT in a browser.

Very clear example...... – Triztian May 17 at 19:02.

My understanding of REST operations is that the URL uniquely identifies the resource, while the body of the request contains the representation of the resource. Given that, it's questionable whether either of your options are truly RESTful. The first would be, assuming that the resource is named "Players" and a GET on that resource returns a list of players (I won't get into the question of whether that GET returns other resource URLs or not ... Fielding would say that it should, with individual requests to get the resource data).

The second would be, assuming that the request body contained information keyed by name "Gretsky". However, that requires you to generate the keys externally.

For the record, Fielding is right. Your /players representation should provide hyperlinks to the representations at /players/gretsky, etc. He gave a lot of really good reasons why out-of-band information is a bad idea, and I think history is very slowly proving him right. All of the best internet-scale protocols essentially do this, and the ones that don't tend to be frustrating and difficult to implement clients for.

– Bob Aman Oct 24 '09 at 23:21 @Bob Re-read section 6.2 of Roy's dissertation. URIs are Uniform RESOURCE Identifiers.As Roy states, "URI identifies a concept rather than a document". – Darrel Miller Oct 25 '09 at 2:40 I've deleted the comment, because I can see why it could be wildly misunderstood, though I still stand by the point that more than one URI can legitimately point at a single logical resource.

A URI can identify a representation as well as a resource. – Bob Aman Oct 25 '09 at 3:10 Yes, you are correct. Multiple urls are often used to point to different representations of the same resource.

Some people argue that they become different resources at that point.It is an often debated issues. – Darrel Miller Oct 25 '09 at 3:33 Regarding returning hyperlinks rather than the literal contents of collections: I have a hard time accepting this. First, because you have to pay overhead to create N new requests.

But more important, because the client always has to know how the server presents data. So the difference between /Players returning a bunch of /Players/1234 URLs, and /Players returning the actual data is rather like counting angels on a pin. – kdgregory Oct 25 '09 at 20:05.

Option #1 is fine, though probably overkill. Option #1 is not fine because it's not idempotent. Option #2 is a BAD idea.

That would be misusing PUT. PUT should be used primarily when your request data payload is an opaque block of data, usually either large or hierarchical. Smaller, non-hierarchical payloads make more sense as POST.

Also, try to avoid changing state via query parameters. There's nothing technically dangerous about that if it's not a GET request, but it's not really RESTful. In this case, what you should be doing is: POST /players HTTP/1.1 Host: www.example.com Content-Type: application/x-www-form-urlencoded Content-Length: 12 name=Gretsky This should return a 201 Created response.(There is an exception to this: If you don't create the resource immediately, and it might be rejected at a later time, use 202 Accepted instead.) Writing a REST web service that uses more of HTTP than POST and GET should only be done after having read the HTTP specification.

(It's a very useful read. ) That rule is a bit looser if you're using a framework that makes all the decisions for you.

Option 1 is not fine if the intent is to add a new player to an existing list of players. Where have you seen it suggested that payload size and shape has an impact on the choice between PUT and POST? I am not aware of any REST constraint that would prevent you from using a POST and a query parameter to change state.

– Darrel Miller Oct 25 '09 at 2:21 Yeah... probably not clear what I meant. The point is that PUT should be idempotent and there should be a corresponding ability to GET whatever you PUT. This makes good sense for large or hierarchical data, because you're likely to want to retrieve the same data intact.

Whereas with POST you don't have these constraints, and you're free to optimize for simplicity, e.g. Application/x-www-form-urlencoded. – Bob Aman Oct 25 '09 at 3:00 Also, you're absolutely right about Option #1. I glazed over it, but yeah, that would violate idempotency.

– Bob Aman Oct 25 '09 at 3:05 "I am not aware of any REST constraint that would prevent you from using a POST and a query parameter to change state. " There isn't one. That's more like a misuse of the URI itself.

– Bob Aman Oct 25 '09 at 3:16 @Bob Why it mis-using the URI? – Darrel Miller Oct 25 '09 at 3:24.

The url used should identify the resource in the body, either by path components or query parameters, though I would prefer path components for something like a name or id. The body should be a representation; the one you PUT should the same or similar as what you GET from the same url (or can get, the in case of multiple formats) Example #1 is inappropriate because you are sending a representation for a single player to a url for all players. POST would be more appropriate in this case.

Example #2 would be slightly inappropriate if extended to all fields because you would then be sending representation data in the url.

I cant really gove you an answer,but what I can give you is a way to a solution, that is you have to find the anglde that you relate to or peaks your interest. A good paper is one that people get drawn into because it reaches them ln some way.As for me WW11 to me, I think of the holocaust and the effect it had on the survivors, their families and those who stood by and did nothing until it was too late.