Best way in REST api to request a summary representation of a resource?

Question

I have a REST api that deals with a large resource, customers. The client sometimes wants an abbreviated/summary representation of a customer. What would be a good way to specify that the request is for a summary representation?

To get a full representation for customer 123 its: /customers/123

To get a summary representation is /customers/123/summary a good way? Are there better options?

Answer 1

To make your solution reusable and flexible, I would suggest implementing a "filter" query parameter. In there, you can put any fields required by the client:

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

That way if later you need to create a different summary for a different task, you won't have anything to modify.

I wouldn't recommend /customers/123/summary because it's not flexible. It might be ok for one case, but if the client needs to access different properties for a different case, you will have to tweak the resource (most likely by returning more fields than needed). If you want to "hide" the field names, perhaps an alternative could be something like this:

GET /customers/123?view=DESCRIPTION

Where "DESCRIPTION" would 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 since you can easily create new views.