Different Resource Representations (REST API)

Question

Hi,

I'm developing a REST API and I have a question about resource representations.

Suppose I got the "person" resource under the /app/person/{id} URI. I need an XML representation, that basically is all the object fields as XML nodes under the root. Now requirements indicate that we must also support another kind of XML representation enforced by a proprietary schema.

The question is: is it under REST best practices to support a proprietary content type like "text/my-type" for the same resource? note that both are XML but formatted differently, and most important they don't carry the same information (eg. one representation may include other fields like "modified-since")

Important!: I know that being pragmatic and keeping it simple it's more important than guides and "best practices" but I just wanted to know if that's the way to go under a RESTful architecture.

Answer 1

If these are just two different representations of a Person resource, then you ought to have two media types for them. If at all possible try to find and reuse standard representations and their media types (see http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven). Both media types should have the form application/type+xml (and see Darrel's comment).

Answer 2

Yes and no. There are no REST constraints that prevent you from returning two different representations of a resource from the same URL. Even, if one media type is a proprietary format. Be careful about allowing the content to vary too much, I hear that some people get pretty upset about that. Also, for the custom formats you should use a media type under the vendor subtree

e.g. application/vnd.companyname.format+xml

However, it is not really in the spirit of REST to return proprietary formats. That being said, you can do with without any problems other than limiting serendipitous re-use.

Answer 3

Content Negotiation is built into HTTP using the Accept and Accept-Encoding headers. The client apps should specify what type they want returned by setting these headers.

Answer 4

If the second format is simply a different syntax (or can reasonably be viewed as such), it's perfectly fine (and RESTful and in compliance with REST best practices) to add it as a second representation with another media type. If you consider the difference to be more than syntactical, you should probably create a different resource. The same is true if you want to be able to link to a specific representation (because it needs a different URI if you want to do so). In this latter case, you might want to consider a canonical, format-independent resource as well that can return a 303 See Other with links to the specific ones.