I'm storing files as REST API resources, sending and receiving them as base64 strings, along with some other metadata. What's the best way to handle GET for the collection? (e.g GET .../api/files)

The standard response to GETting the collection (to my understanding) is to return the full contents of all resources, but in this case that would return a lot of data; does it violate REST standards to just return a list of the resource IDs? The other logical option is to return some sort of reference to the file data in each resource, but the other way seems cleaner.

  • 1
    »The standard response to GETting the collection (to my understanding) is to return the full contents of all resources« where does this come from? Jun 30, 2017 at 7:42

2 Answers 2


In a RESTful API, a GET for a collection should return a representation of the collection.

There is no requirement that the representation of a collection contains the full representations of the elements of the collection.
One thing that I would expect as part of the representation of a collection is a link for each element indicating where that element can be accessed. Besides that, you can include as much or as little of the representation of the elements as you think is useful for your users/clients.


Your approaches do not violate the constraints that a RESTful system must met, which are: client-server, stateless, cacheable, layered system, code on demand (optional) and uniform interface. See wikipedia for more details.

I would go with the first option: "return the full contents of all resources" (maybe everything nicely organized in a JSON) since it is straightforward.

After everything is running, if that give me trouble (like bad performance), then I would start looking for other ways...

  • Returning the full contents of all resources won't be performant as soon as the total data size reaches tens / hundreds of megabytes; which one of the other ways (returning all IDs, or returning all with files as references) seems cleaner? Jun 30, 2017 at 1:11
  • 1
    Or maybe implement pagination? I have no idea if that's acceptable in this REST scenario, though.
    – MetaFight
    Jun 30, 2017 at 3:52
  • @LukasPalmer I would go with the ID. It seems more cleaner and "more secure" than using a direct reference to the files (like an URL).
    – sotobuild
    Jun 30, 2017 at 6:27
  • 1
    Resource representations are not necessarily the resource Itself. They are just that, representations. A common file representation is a URL/URI (file path). The file, as a binary is yet another respresentation (CSV, Excel, PDF,...). So in this case I don't see the need of returning the content of each file as part of its representation. Overall in JSON format. It could perphaps, to embed some attributes regarding the file metadata such as name, creation date, last update date, etc...
    – Laiv
    Jul 1, 2017 at 10:07

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.