Different RESTful representations of the same resource

Question

My application has a resource at /foo. Normally, it is represented by an HTTP response payload like this:

{"a": "some text", "b": "some text", "c": "some text", "d": "some text"} 

The client doesn't always need all four members of this object. What is the RESTfully semantic way for the client to tell the server what it needs in the representation? e.g. if it wants:

{"a": "some text", "b": "some text", "d": "some text"} 

How should it GET it? Some possibilities (I'm looking for correction if I misunderstand REST):

• GET /foo?sections=a,b,d.
  • The query string (called a query string after all) seems to mean "find resources matching this condition and tell me about them", not "represent this resource to me according to this customization".
• GET /foo/a+b+d My favorite if REST semantics doesn't cover this issue, because of its simplicity.
  • Breaks URI opacity, violating HATEOAS.
  • Seems to break the distinction between resource (the sole meaning of a URI is to identify one resource) and representation. But that's debatable because it's consistent with /widgets representing a presentable list of /widget/<id> resources, which I've never had a problem with.
• Loosen my constraints, respond to GET /foo/a, etc, and have the client make a request per component of /foo it wants.
  • Multiplies overhead, which can become a nightmare if /foo has hundreds of components and the client needs 100 of those.
  • If I want to support an HTML representation of /foo, I have to use Ajax, which is problematic if I just want a single HTML page that can be crawled, rendered by minimalist browsers, etc.
  • To maintain HATEOAS, it also requires links to those "sub-resources" to exist within other representations, probably in /foo: {"a": {"url": "/foo/a", "content": "some text"}, ...}
• GET /foo, Content-Type: application/json and {"sections": ["a","b","d"]} in the request body.
  • Unbookmarkable and uncacheable.
  • HTTP does not define body semantics for GET. It's legal HTTP but how can I guarantee some user's proxy doesn't strip the body from a GET request?
  • My REST client won't let me put a body on a GET request so I can't use that for testing.
• A custom HTTP header: Sections-Needed: a,b,d
  • I'd rather avoid custom headers if possible.
  • Unbookmarkable and uncacheable.
• POST /foo/requests, Content-Type: application/json and {"sections": ["a","b","d"]} in the request body. Receive a 201 with Location: /foo/requests/1. Then GET /foo/requests/1 to receive the desired representation of /foo
  • Clunky; requires back-and-forth and some weird-looking code.
  • Unbookmarkable and uncacheable since /foo/requests/1 is just an alias that would only be used once and only kept until it is requested.

Answer 1

I would suggest the querystring solution (your first). Your arguments against the other alternatives are good arguments (and ones that I've run into in practise when trying to solve the same problem). In particular, the "loosen the constraints/respond to foo/a" solution can work in limited cases, but introduces a lot of complexity into an API from both implementation and consumption and hasn't, in my experience, been worth the effort.

I'll weakly counter your "seems to mean" argument with a common example: consider the resource that is a large list of objects (GET /Customers). It's perfectly reasonable to page these objects, and it's commonplace to use the querystring to do that: GET /Customers?offset=100&take=50 as an example. In this case, the querystring isn't filtering on any property of the listed object, it's providing parameters for a sub-view of the object.

More concretely, I'd say that you can maintain consistency and HATEOAS through these criteria for use of the querystring:

• the object returned should be the same entity as that returned from the Url without the querystring.
• the Uri without the querystring should return the complete object - a superset of any view available with a querystring at the same Uri. So, if you cache the result of the undecorated Uri, you know you have the full entity.
• the result returned for a given querystring should be deterministic, so that Uris with querystrings are easily cacheable

However, what to return for these Uris can sometimes pose more complex questions:

• returning a different entity type for Uris differing only by querystring could be undesirable (/foo is an entity but foo/a is a string); the alternative is to return a partially-populated entity
• if you do use different entity types for sub-queries then, if your /foo doesn't have an a, a 404 status is misleading (/foo does exist!), but an empty response may be equally confusing
• returning a partially-populated entity may be undesirable, but returning part of an entity may not be possible, or may be more confusing
• returning a partially populated entity may not be possible if you have a strong schema (if a is mandatory but the client requests only b, you are forced to return either a junk value for a, or an invalid object)

In the past, I have tried to resolve this by defining specific named "views" of required entities, and allowing a querystring like ?view=summary or ?view=totalsOnly - limiting the number of permutations. This also allows for definition of a subset of the entity that "makes sense" to the consumer of the service, and can be documented.

Ultimately, I think that this comes down to an issue of consistency more than anything: you can meet HATEOAS guidance using the querystring relatively easily, but the choices you make need to be consistent across your API and, I'd say, well documented.

Answer 2

I've decided on the following:

Supporting few member combinations: I'll come up with a name for each combination. e.g. if an article has members for author, date, and body, /article/some-slug will return all of it and /article/some-slug/meta will just return the author and date.

Supporting many combinations: I'll separate member names by hyphens: /foo/a-b-c.

Either way, I'll return a 404 if the combination is unsupported.

Architectural constraint

REST

Identifying resources

From the definition of REST:

a resource R is a temporally varying membership function M_R(t), which for time t maps to a set of entities, or values, which are equivalent. The values in the set may be resource representations and/or resource identifiers.

A representation being an HTTP body and an identifier being a URL.

This is crucial. An identifier is just a value associated with other identifiers and representations. That's distinct from the identifier→representation mapping. The server can map whatever identifier it wants to any representation, as long as both are associated by the same resource.

It's up to the developer to come up with resource definitions that reasonably describe the business by thinking of categories of things like "users" and "posts".

HATEOAS

If I really care about perfect HATEOAS, I could put a hyperlink somewhere in the /foo representation to /foo/members, and that representation would just contain a hyperlink to every supported combination of members.

HTTP

From the definition of a URL:

The query component contains non-hierarchical data that, along with data in the path component, serves to identify a resource within the scope of the URI's scheme and naming authority (if any).

So /foo?sections=a,b,d and /foo?sections=b are distinct identifiers. But they can be associated within the same resource while being mapped to different representations.

HTTP's 404 code means that the server couldn't find anything to map the URL to, not that the URL is not associated with any resource.

Functionality

No browser or cache will ever have trouble with slashes or hyphens.