Is this RESTfull? - api

Question

I'm a little confused as to what the collection URI's should return.
Say I have a collection, /users of decently large elements. Then we have the expected:
GET /users/123 // returns user element with identifier 123
But what should
GET /users
return? If the collection is large, and the elements are large, it's probably not a good thing to return all elements. Perhaps instead, GET requests at the /users level should return element summaries (identifiers and possibly a few properties), while GET requests at the /users/ level should return actual elements. Then you could do something like;
GET /users
> [{name: abc, id: 1}, {name: def, id: 2}, {name: ghi, id: 3}, ...]
GET /users/2
> {name: def, prop1: *, prop2: *, ...}
Which could be a good way to lazily load data if you wanted to preview important application-domain properties before requesting them in their entirety. With this, in order to apply queries, you'd do something like
GET /users?prop1=value // returns element summaries of elements with prop1=value
GET /users/?prop1=value // returns elements with prop1 = value
Is this approach OK? Or do the other methods acting on /users then loose meaning.. (ex. PUT /users ?)

Answer 1

I personally like the style where /users does not return all users but returns information needed to then query specific users. So the summaries approach is how I would generally write it.
If you were filtering or querying, I would go with the first one you provided:
GET /users?prop1=value
I don't care for the second one
GET /users/?prop1=value
because it can be easily misunderstood or lead to confusing and unintended bugs (missing one slash still works but completely changes the results).
You might want to go with an approach of an alternative URL for returning specific users based on search parameters such as
GET /users?prop1=value // returns element summaries based on results of prop1 matching
GET /users/find?prop1=value // returns elements with prop1 = value
Obviously your wording could change (find/search) or you could use a completely different URI but I try to avoid things where two different meanings are a single character/symbol apart to avoid unintended mistakes. Another option would be to make sure you outline this clearly in provided documentation so anyone consuming your API is alerted about this potential.
Actually expanding on this I would go with the all construct.
So instead of using find/search I would provide:
GET /users // returns summaries
GET /users/# // returns element
GET /users/all // returns all elements
GET /users/all?prop1=value // returns all elements that match the filter