My question is about designing an endpoint for getting a list of items in a collection. Here my understanding is that a GET on a collection returns a list of the items in that collection, but no details about these.
A list of resource IDs isn't very nice for a human being, so a GUI front-end would then request details of each item in the collection.
If the collection is say the "users" then the GET on the collection just returns a list of user IDs (ALL OF THEM! Paged, I imagine?)
The GUI then requests details for every ID and uses this to populate an interface. For a list you might say, as an example, just show the user's Full name and Email address in this interface, allowing the user to select one to see more details.
Now I'm thinking it would save a lot of back and forward between the client and the API if the "list retrieve" returned a bit more than just the IDs, maybe include ID, full-name and Email address for each item.
Does that break RESTful-ness? Where do you stop with how much detail to return in a single request? Do you allow the client to specify which attributes to include as part of the request?
What about "searching" a collection? Do you allow arguments to be specified on the GET against the collection to "filter" the results?
The API exists to service the needs of the clients. If your clients need the details, you should be returning them.
That said, there's a tradeoff for highly-cacheable items. If the list is not static but the contents are, you might be better served returning the list of links. Then the client makes one call for each element, and they sit in the cache. Later calls for those elements get served by an intermediate cache, either on the client or somewhere between client and server. That would reduce overall bandwith of calls to the list at the cost of a larger absolute number of calls at first.
Another option is to support a query parameter like ?include=id, full-name, email. By default just return the self link, but clients may specify what properties they'd like to have populated in the representations they get back. If you support this query parameter, I would suggest defaulting to returning only the most essential information.
As far as searching the collection, it depends on the nature and complexity of the search. Query parameters are one option. Using POST to a search endpoint and sending up the search criteria in the body is also reasonable, especially if your url might be longer than 2k characters (the default url length limit for some browsers). You can also do saved searches this way - let the POST create a search criteria resource on the server, and let clients GET /widgets?search-criteria=<id>.