Different RESTful representations of the same resource

by

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.

Leave a Comment