38

What's the rule of thumb for passing data in a REST URL in the query string vs. the body of a request?

Ie: You're creating a service to add hockey players. You could go with:

PUT /players { "name": Gretzky }

or

PUT /players?name=Gretzky

If you're passing a lot of data, you would need to go with option #1 as there is a limit on the URL length. But other than this, why not just use the query string to pass data?

Update: Removed comment that you could test option #2 in a browser. Realized (duh) that you can only do GET-s in your browser.

Improve this question
3
  • 1
    You can test posts and puts in your browser by using plugins. E.g. Poster in FireFox. Commented Mar 7, 2012 at 23:22
  • 1
    or just pull up the console and do a $.ajax Commented Feb 11, 2013 at 22:29
  • Does this answer your question? REST API Best practices: Where to put parameters? Commented Nov 27, 2019 at 8:56

4 Answers 4

Reset to default
36

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.

Improve this answer
Sign up to request clarification or add additional context in comments.

2 Comments

@Darrel Could you also do the following?... POST /players?name=Gretzky
@NikoBellic Yes, you can do that. It's not common but there is nothing wrong with it.
3

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.

Improve this answer

16 Comments

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.
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.
Also, you're absolutely right about Option #1. I glazed over it, but yeah, that would violate idempotency.
"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.
I will accept that there may be better ways to do it in many cases, but I just want people to be more careful about throwing around the "that's not RESTful" line. If you can't match it to a REST constraint that it violates, then just limit it to saying that you wouldn't do it.
|
2

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.

Improve this answer

6 Comments

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 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".
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.
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.
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.
|
-2

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.

Improve this answer

Comments

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.