RESTful collections & controlling member details

I have come across this issue a few times now, and each time I make a f开发者_运维知识库ruitless search to come up with a satisfying answer.

We have a collection resource which returns a representation of the member URIs, as well as a Link header field with the same URIs (and a custom relation type). Often we find that we need specific data from each member in the collection.

• At one extreme, we can have the collection return nothing but the member URIs; the client must then query each URI in turn to determine the required data from each member.

• At the other extreme, we return all of the details we might want on the collection. Neither of these is perfect; the first can result in a large number of API calls, and the second may return a lot of potentially unneeded information.

Of the two extremes I favour the second in our case, since we rarely use this for more than one sutiation. However, for a more general approach, I wondered if anyone had a nice way of dynamically specifying which details should be included for each member of the collection? I guess a query string parameter would be most appropriate, but I don't want to break the self-descriptiveness of the resource.

I prefer your first option..

At one extreme, we can have the collection return nothing but the member URIs; the client must then query each URI in turn to determine the required data from each member.

If you are wanting to reduce the number of HTTP calls over the wire, for example calling a service from a handset app (iOS/Android). You can include an additional header to include the child resources:

X-Aggregate-Resources-Depth: 2

Your server side code will have to aggregate the resources to the desired depth.

Sounds like you're trying to reinvent PROPFIND (RFC 4918, Section 9.1).

I regularly contain a subset of elements in each item within a collection resource. How you define the different subsets is really up to you. Whether you do,

/mycollectionwithjustlinks
/mycollectionwithsubsetA 
/mycollectionwithsubsetB

or you use query strings

/mycollection?itemfields=foo,bar,baz

either way they are all different resources. I'm not sure why you believe this is affecting the self-descriptive constraint.