Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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

Tags:

rest

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 (or a link) of all available file resources instead of retrieving the full representation because it would be too much data.

GET /files        # return the full representation of a collection of resources
GET /files/{id}   # return the full representation of a single resource 

I don't know if it is better to split it in two different resources:

GET /fileids      # return only IDs
GET /files/{id}   # return the full representation of a single resource

What would be your approach?

like image 444
chrpinedo Avatar asked May 26 '16 09:05

chrpinedo


People also ask

What is the recommended method and URL pattern for retrieving a specific user?

The GET /api/v2/users/{id} endpoint allows you to retrieve a specific user using their Auth0 user ID. This endpoint is immediately consistent, and as such, we recommend that you use this endpoint for: User searches run during the authentication process.

How do you represent resources in REST?

REST uses various representations to represent a resource where Text, JSON, XML. The most popular representations of resources are XML and JSON.

What is resource ID in REST API?

Each REST API resource can be accessed by using a Uniform Resource Identifier (URI). The URI must contain the correct connection information to successfully call the API. The connection information consists of the host name where the web management service is running, and the port number that the service is using.

Which URL pattern is recommended when working with one resources and a collection of resources?

Relative vs Absolute. It is strongly recommended that the URLs generated by the API should be absolute URLs. The reason is mostly for ease of use by the client, so that it never has to find out the correct base URI for a resource, which is needed to interpret a relative URL.


1 Answers

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
like image 135
cassiomolin Avatar answered Nov 03 '22 02:11

cassiomolin