Different Resource Representations (REST API)

Question

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

Suppose I have 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.

My question: is it in accordance with 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 importantly they don't carry the same information (e.g. one representation may include other fields like modified-since).

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

Answer 1

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.

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.