A partial representation is one where the client would ask for a specific bits and pieces of a representation, such as Amazon serving a partial representation of a book containing just the table of contents, or just the reviews and comments. The problem is quite simple, and a solution like the following would work:
GET /book/0-374-29288-4?view=toc GET /book/0-374-29288-4?view=reviews GET /book/0-374-29288-4?fields=reviews,comments
At Yahoo!, we call this the "view" pattern. The key thing to note here is that the names of views or fields don't necessarily refer to particular members of representations – such as elements/attributes in XML-family of representations or properties in JSON representations. It is up to the server to define what the values of those parameters mean. They could potentially mean inclusion/exclusion of different members of representations in particular media types. This way, we can let URIs remain decoupled from particular media types. I consider this important to let the system evolve to support conneg for what it is designed for.
Flickr solves the same use case by taking an extras query parameter with a list of fields to include for its search API.
Another reason we adopted this pattern for serving partial representations is that this approach lets us link to those representations, as in
<link href="/book/0-374-29288-4?view=toc" rel="view"/> <link href="/book/0-374-29288-4?view=reviews" rel="view"/> <link href="/book/0-374-29288-4?fields=reviews,comments" rel="view"/>
By being able to link like this, we can take advantage of HATEOAS as well as do some interesting things that only opaque URIs let us do.
Although this approach is quite common, once in a while we come across some proposals that deserve a bit more scrutiny.
The most recent approaches that I came across with are from the RESTful JSON proposal. The first is based on a new "locator" media type parameter. In this model, a client would include a header such as
Content-Type: application/json;locator=my_id[{"my_id":"1","name":"John Doe"},{"my_id":"2","name":"Jane Doe"}]
The idea of this locator is to identify a sub-resource. This is an interesting but questionable usage of the Content-Type header. I say questionable because the purpose of the Content-Type header is to indicate the media type of the entity enclosed in the body of a request or a response. Here, what is included is not just a media type of the entity. It is also encoding data, thus mixing up resource naming and resource data. In RESTful systems, we use URIs to name resources, and let headers provide metadata of a request/response or the entity enclosed within a request/response.
The same proposal includes another idea to deal with partial representations of collections of resources. That is to rely on the Range and Content-Range headers. Here is an example.
GET /Person/ HTTP/1.1 Range: items=0-1 Content-Range: items 0-1/33 ...
Here, the client is asking for the first two elements of a collection using the Range header.
In HTTP, Both Content-Range and Range headers describe byte ranges. See Sec 3.12 of RFC 2616, which recognizes "bytes" as the unit of content range. RFC 2616 does allow extensions, but software that can recognize byte ranges is likely going to trip when it sees extensions like this.
Most importantly, both these approaches prevent linking. You can't claim a solution to be RESTful if you can’t use it to link to a resource or a representation.
{ 3 comments… read them below or add one }
+1 subbu!
i’ve been mostly idling on the RESTful-JSON list (posted a few items) primarily because their trajectory is a bit off the mark, IMHO. you put it quite succinctly, too.
thanks!
Do you guys update partial representations? How would you update the TOC for a book?
No, we don’t, for a few reasons. I will describe those in a follow up post.
{ 1 trackback }