Best way in a REST api to request a brief view of a resource?

Question

I have a REST api that deals with a large resource, clients. The client sometimes wants to get a shortened / final presentation of the client. What would be a good way to indicate that the request is for a summary view?

To get a complete picture for customer 123 his: /customers/123

Getting a final view of /customers/123/summary good way? Are there any better options?

Answer 1

To make your solution reusable and flexible, I would suggest implementing the filter request parameter. There you can put any fields required by the client:

 GET /customers/123?fields=id,first_name,last_name,email 

Thus, if you later need to create another resume for another task, you will have nothing to change.

I would not recommend /customers/123/summary because it was not flexible. This may be good for one case, but if the client needs to access various properties for another case, you will have to configure the resource (most likely, returning more fields than necessary). If you want to “hide” field names, an alternative might be something like this:

 GET /customers/123?view=DESCRIPTION 

Where " DESCRIPTION " will describe the type of summary. For example:

 GET /customers/123?view=addresses_only // eg. returns billing and home address GET /customers/123?view=short // eg. returns only id, first name, last name 

This is still flexible as you can easily create new views.