REST Content-Type: Should it be based on extension

Question

Should the representation(html, xml, json) returned by a RESTful web service be determined by the url or by the Accept HTTP header?

Answer 1

See Chapter 5 - Representational State Transfer (REST), section 5.2.1.2 Representations of Roy Fielding's dissertation on Architectural Styles:

The data format of a representation is known as a media type [48].

Looking at the link, we see that it refers to MIME. So I assume that in HTTP parlance, it is represented with a Content-Type header for POST/PUT and Accept header for GET.

Here is the rest of the paragraph (for completeness):

A representation can be included in a message and processed by the recipient according to the control data of the message and the nature of the media type. Some media types are intended for automated processing, some are intended to be rendered for viewing by a user, and a few are capable of both. Composite media types can be used to enclose multiple representations in a single message.

P.S.: I am not sure why people never look in the place where REST is actually defined...

Answer 2

Use the Accept header if provided, URI as a failover.

Answer 3

Both are valid. Quote from xml.com:

A resource may have more than one representation. There are four frequently used ways of delivering the correct resource representation to consumers:

1. Server-driven negotiation. The service provider determines the right representation from prior knowledge of its clients or uses the information provided in HTTP headers like Accept, Accept-Charset, Accept-Encoding, Accept-Language, and User-Agent. The drawback of this approach is that the server may not have the best knowledge about what a client really wants.
2. Client-driven negotiation. A client initiates a request to a server. The server returns a list of available of representations. The client then selects the representation it wants and sends a second request to the server. The drawback is that a client needs to send two requests.
3. Proxy-driven negotiation. A client initiates a request to a server through a proxy. The proxy passes the request to the server and obtains a list of representations. The proxy selects one representation according to preferences set by the client and returns the representation back to the client.
4. URI-specified representation. A client specifies the representation it wants in the URI query string.

Answer 4

There are problems with using content type... I discussed this on my blog http://shouldersofgiants.co.uk/Blog and finally settled on including the representation in the URI as suggested in RESTful Web Services by Richardson and Ruby

Answer 5

This is a non-question.

Accept depends on conneg (content negotiation). Conneg will let the client decide what media type they accept through the Accept: header. The response will then be in that format, together with a Vary: Accept header.

On the other hand, it's also possible and perfectly valid to expose your resource as /resource.json and /resource.xml.

The ideal is to implement both: /resource (generic uri that supports conneg) /resource.xml /resource.json

the conneg'd version returned by /resource can simply redirect to the correct uri based on the negotiated media type. Alternatively, the correct representation can be returned from the generic uri, and use Content-Location to specify the sepcific representation that was returned.

Answer 6

Since you're mentioning a RESTful web service and not any web service, I would strongly go for what is supported by underlying standard - HTTP 1.1 and its content negotiation that relies on Accept HTTP header.

As I've explained in my answer to Can I change the headers of the HTTP request send by the browser, address (URI) and representation are two distinct pillars of a RESTful design and they do not need to be mixed. One should not abuse URI for embedding acceptable representations when there's Accept header.

Only if your web application is potentially run and used in an environment where's some HTTP header filtering involved by intermediate nodes, then you should support URI-based content negotiation. Truth be told, such intrusive or improperly functioning proxies should be replaced if anyhow possible and feasible.

Cheers!
Shonzilla