Multiple records with one request in RESTful syste

Question

All the examples I've seen regarding a RESTful architecture have dealt with a single record. For example, a GET request to mydomain.com/foo/53 to get foo 53 or a POST to mydomain.com/foo to create a new Foo.

But what about multiple records? Being able to request a series of Foos by id or post an array of new Foos generally would be more efficient with a single API request rather than dozens of individual requests. Would you "overload" mydomain.com/foo to handle requests for both a single or multiple records? Or would you add a mydomain.com/foo-multiple to handle plural POSTs and GETs?

I'm designing a system that may potentially need to get many records at once (something akin to mydomain.com/foo/53,54,66,86,87) But since I haven't seen any examples of this, I'm wondering if there's something I'm just not getting about a RESTful architecture that makes this approach "wrong".

Answer 1

There is a good reason for not returning multiple records in a single request, it's less cache-able and less scalable. Anytime you wonder how or why REST is supposed work, look at a web page. When you request a page, it comes down with links to other resources like multiple images, css files, js files, etc.

While it might seem more efficient to try and pump all those over a single request, it's much more scalable and cache-able to treat them all as separate resources and allow the web server and keep-alive connections to deal with making the request of many resources efficient. If you inlined all that css, javascript, and images into some single download that could represent the entire page, when you visit another page that needs some of the same resources, you have to download them all again because you didn't reference them properly as an individual resource the first time that the browser could cache.

When you do have something that represents a list of multiple resources, the restful way to do it is to have the list be nothing but a list of urls to the individual resources and to fetch each one of the separately, just as say web pages at flicker contain urls to all the images on the page, it doesn't try and inline them all into the page itself.

When resources properly allow caching and are referenced individually, the cache hit rate can get absurdly high allowing the web server to handle much more load and allowing caching proxy servers between the client and the server to prevent the request from even having to hit the server. The web works well using this approach, before thinking it sounds crazy, think about that.

Answer 2

While I don't see anything intrinsically wrong with your approach, it seems a little odd for a user of your API to want foo records with arbitrary IDs. I'd immediately suspect that they are using the IDs to represent a different concept, e.g., all the foos that were created in the last week, etc. If that's what they're doing, then you should probably expose that functionality on the server instead of using the list of IDs as a surrogate.

Answer 3

This is an old question, but nevertheless, I'm writing this for anyone who may land here while searching for an answer.

There are plenty of valid reasons for an application to request multiple records specified by IDs, and no, there need not be any logic like "created last week", or "created between Date1 and Date2", etc. Imagine a situation where the user is presented with a grid/list of records and they can manually select multiple records for further processing.

That being said, many solutions are already suggested here: How to construct a REST API that takes an array of id's for the resources

However, IMHO the best solution is the one by @nilesh in the same discussion: https://stackoverflow.com/a/32436345/134120

First do a POST passing the IDs you want to get, the server will return a batch ID, and then you do a GET with that batch ID to get all the records.