Retrieving a collection of IDs instead of the full representation of a resource in REST

Question

I\'m designing a REST API for the first time, so I have what I consider a quite basic question about its design.

I would like the files collection to return an ID (o

Answer 1

Custom media type

You could have a custom media type for the full representation of the resource and a custom media type for the identifiers of the files.

For example, you could use one of the following (or both) media types to retrieve a full representation of a collection of files:

GET /api/files HTTP/1.1
Host: example.com
Accept: application/json

GET /api/files HTTP/1.1
Host: example.com
Accept: application/vnd.company+json

And the following media type to retrieve only the identifiers of the files:

GET /api/files HTTP/1.1
Host: example.com
Accept: application/vnd.company.id+json

Query string parameter

Alternatively, you could support selecting the fields to be retrieved with a query string parameter.

Use the following to retrieve the full representation of a collection of files:

GET /api/files HTTP/1.1
Host: example.com
Accept: application/json

And the following to retrieve only the identifiers of the files:

GET /api/files?fields=id HTTP/1.1
Host: example.com
Accept: application/json

The field query parameter could support a list of values separated by commas, allowing the selection of multiple fields/properties:

GET /api/files?fields=id,name,author HTTP/1.1
Host: example.com
Accept: application/json