Menu
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?
444
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.
REST uses various representations to represent a resource where Text, JSON, XML. The most popular representations of resources are XML and JSON.
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.
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.
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
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
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
