89

I have a url to fetch appointments for a user like this:

/user/:userId/appointments

How should the url look like if I want to get appointments for multiple users?

should it be:

/appointments?users=1d1,1d2..

Thanks, Chris.

ChrisOdney
  • 6,066
  • 10
  • 38
  • 48

6 Answers6

105

Collections are a resource so /appointments is fine as the resource.

Collections also typically offer filters via the querystring which is essentially what users=id1,id2... is.

So, 

/appointments?users=id1,id2

is fine as a filtered RESTful resource.

bryanmac
  • 38,941
  • 11
  • 91
  • 99
22

Another way of doing that, which can make sense depending on your server architecture/framework of choice, is to repeat the same argument over and over again. Something like this:

/appointments?users=id1&users=id2

In this case I recommend using the parameter name in singular:

/appointments?user=id1&user=id2

This is supported natively by frameworks such as Jersey (for Java). Take a look on this question for more details.

Community
  • 1
  • 1
Gilberto Torrezan
  • 5,113
  • 4
  • 31
  • 50
  • also in golang i found 2 libraries is doing it like your example not with comma separated [google/go-querystring](https://github.com/google/go-querystring/query) and [gorilla/schema](https://github.com/gorilla/schema) – Isaac Weingarten Aug 18 '21 at 00:05
  • This is the way Swagger or OpenAPI Spec describes it, if you define a multiselect picklist as a query parameter. I vote for this solution! – Sauer Jul 13 '22 at 15:30
  • This is also the way how Node.js would decode the query as an array. [querystring.parse](https://nodejs.org/dist/latest-v18.x/docs/api/querystring.html#querystringparsestr-sep-eq-options) – zauni Jan 27 '23 at 08:13
17

I think it's a better practice to serialize your REST call parameters, usually by JSON-encoding them:

/appointments?users=[id1,id2]

or even:

/appointments?params={users:[id1,id2]}

Then you un-encode them on the server. This is going to give you more flexibility in the long run.

Just make sure to URLEncode the params as well before you send them!

sgress454
  • 24,870
  • 4
  • 74
  • 92
  • 5
    ?{users:[id1,id2]} doesn't follow querystring params conventions of ?key1=val2&key2=val2. – bryanmac Aug 14 '12 at 01:45
  • 2
    Also, do you have example of major services offering serialized objects in querystring filters? From what I've seen most offer simple filters of comma delimited options or query formats like OData – bryanmac Aug 14 '12 at 01:46
7

This worked for me.

/users?ids[]=id1&ids[]=id2
Ravi MCA
  • 2,491
  • 4
  • 20
  • 30
  • This method also has the added benefit of allowing comma's to be present in the array values too, not that you would have that in an id value, but there may be some edge case I suppose. – alexkb Jun 19 '23 at 01:43
2
/appointments?users=1d1,1d2..

is fine. It's pretty much your only sensible option since you can't pass in a body with a GET.

Oleksi
  • 12,947
  • 4
  • 56
  • 80
-8

Instead of using http GET, use http POST. And JSON. Or XML

This is how your request stream to the server would look like.

POST /appointments HTTP/1.0
Content-Type: application/json
Content-Length: (calculated by your utility)

{users: [user:{id:id1}, user:{id:id2}]}

Or in XML,

POST /appointments HTTP/1.0
Content-Type: application/json
Content-Length: (calculated by your utility)

<users><user id='id1'/><user id='id2'/></users>

You could certainly continue using GET as you have proposed, as it is certainly simpler.

/appointments?users=1d1,1d2

Which means you would have to keep your data structures very simple.

However, if/when your data structure gets more complex, http GET and without JSON, your programming and ability to recognise the data gets very difficult.

Therefore,unless you could keep your data structure simple, I urge you adopt a data transfer framework. If your requests are browser based, the industry usual practice is JSON. If your requests are server-server, than XML is the most convenient framework.

JQuery

If your client is a browser and you are not using GWT, you should consider using jquery REST. Google on RESTful services with jQuery.

Blessed Geek
  • 21,058
  • 23
  • 106
  • 176
  • 11
    I dont think this is the correct way to go about it. You are GETting a resource not POSTing a new one. – matthew.kempson Jan 27 '16 at 13:08
  • 2
    I don't think you understand the http GET/POST uses. They do not conform to the English dictionary meaning for those words. POST is when trying to GET but with the arguments not placed not in the url but in the io stream. – Blessed Geek Jan 27 '16 at 20:15
  • 1
    It is very perplexing to have someone with an inadequate understanding of the POST method, but depending on the English dictionary meaning, to vote me down. You can't blame me for the syntactic decisions made by the people who chose to define it that way. Don't kill the messenger. – Blessed Geek Jan 28 '16 at 04:24
  • 8
    You CAN use a POST like this but it is not idiomatic - "By design, the POST request method requests that a web server accepts and stores the data enclosed in the body of the request message." https://en.wikipedia.org/wiki/POST_(HTTP) – pherris Apr 20 '16 at 20:52
  • 3
    By historical use in HTML forms, and therefore not the design of REST which came later, POST has been used to not expose request parameters, and is still used that way today. And is the recommended practice. Regardless what wikipedia says. – Blessed Geek Apr 21 '16 at 04:23
  • 2
    [RFC 1945](https://tools.ietf.org/html/rfc1945#section-8.3) (1996, HTTP/1.0 spec) tells to use POST "to create a subordinate of the resource". Later, [RFC 7231](https://tools.ietf.org/html/rfc7231#section-4.3) (2014, HTTP/1.1: Semantics and Content spec) made it more vague by stating "target resource process ... request according to the resource's own specific semantics". So, technically RFCs does not restrict using POST to get some data from the server, but discourage it (in further paragraphs I won't cite here for brevity). – J0HN Feb 28 '17 at 03:31
  • 1
    Historical use in HTML forms have nothing to do with the question or REST - you're not using the paper mail because it has historical use and was a recommended practice of communication some time ago, right? And it's not the recommended practice in general - only when you've got to overcome 4096 URI limitation (is it still in effect though?) or when you don't want to expose parameters (but why would you?). – J0HN Feb 28 '17 at 03:31
  • @BlessedGeek i got what you mean and i´m sorry but i´ll never make a "String Array" instead of changing my method to POST. Totally agree with you. I voted you UP, thank you. – Dante Lacerda Aug 29 '17 at 19:14
  • 1
    Given that browsers and other user agents and webservers behave differently with POST and GET, this seems extremely silly. Of course you can abuse the system, but it'll only lead to pain and inconsistency. The HTTP methods have well-defined, well-understood meanings. People and systems expect these. It's not just wikipedia shouting into the wind. – siride Jan 22 '19 at 15:17
  • I'd say it would be better to just submit identifiers that refer to certain objects in order to obtain them via a HTTP GET, instead of using HTTP POST to submit identifiers to the server. In general, obtaining complex objects should be done with HTTP GET, and submitting complex objects should be done with HTTP POST. Besides that, there seems to be no need for extensibility in regards to the complexity of the identifier needed to obtain the complex objects, even using multiple HTTP GET's would be better than using a POST. – Lennart Jan 06 '20 at 11:28