REST and multiple data formats

Question

Hi guys,

Ok, here is the fact. StackOverflow is implemented REST-style. When you visit a specific questions/$id/ URL you get to see the question. The content is returned in HTML because it's what the browser understands.

I have to develop my own REST service. Fact is that I have to return multiple formats for the same information. For example, the default could be HTML, but I could return also an XML or a JSON.

Question is: what is the recommended style to achieve this ? Three choices (more from your helpful suggestions)

1. option in the URL (e.g. http://example.com/questions/12345/?format=json )
2. different interface (e.g.: for json data you have http://example.com/questions/1234/json/ or http://example.com/json/questions/12345/, for xml data you have http://example.com/questions/1234/xml/ etc... you get the point)
3. http header Accept: application/json

Same is for PUT (POST) operations. If I want to submit data in different formats, I need to inform the receiver the format I am providing, so the same situation (and question) holds.

Thanks!

Edit: Additional proposal is the following

4) Specify a proper URL for each format e.g. http://example.com/questions/12345.json . This looks nice, but wouldn't this mean that, for consistency, we should also have http://example.com/questions/12345.html ? sounds so 1995... :)

PS: I hate markdown putting an arbitrary order to the list. If I want to start with 4, I should be able to do it.

Answer 1

I would go for Option 1 (URL parameter) as it's the most consistent with the principles of REST, and the most pragmatic.

Option 2 smells bad - you're talking about different representations of the same resource, so you should use the same URI for them.

Option 3 smacks of being too hard to control - how would you hand-test it from within your browser, for instance?

(The same arguments apply for PUT / POST.)

Answer 2

It doesn't matter in the slightest between 1. and 2. A URI is opaque, so from the REST interface part of it, there is no difference.

From a caching perspective, 1. will prevent many caches from doing their work.

1. is fine if you want to do conneg against multiple represetnaitons.

Usually though, people use conneg with Accept header, possibly with a redirect to the fully qualified URI using /customer/21.json

Answer 3

Option #3, setting the HTTP "Accept" header, is more in keeping with the HTTP specification and, among REST purists, is considered most correct. It also means that you keep the same URL (resource) no matter what the representation is.

You may, however, encounter user agents that aren't capable of setting an Accept header, so supporting a backup mechanism for specifying the response format is advisable. In that case, I suggest a URL query string parameter. Using a URL query string parameter means you keep the same core URL, no matter the content type returned. This makes it clearer that clients should only issue a PUT to that URL and not to the /foo/bar.json or /foo/bar.xml URLs.

Edit: Another thing to consider if you decide to go with the URL suffix (i.e. foo.json vs. foo?format=json) is that you may run into issues with caching proxies. If someone issues a PUT to /foo.json, a proxy won't interpret that as a request to invalidate /foo.xml. If, however, you use /foo?format=json, then it's all stored under the same resource (/foo) in the proxy.