52

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

7 Answers 7

33

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.
5
  • 1
    What should be the behaviour if both are specified (Accept, and in URL). It's up to developer or maybe there is a convention ? Commented Jun 20, 2011 at 14:19
  • 2
    @ThomasJaskula - If both Accept and in URL are specified, then go with either a.) The most common b.) a sensible or smart default (eg. If you can tell the client is a browser b/c of a UserAgent, then send something that a browser can easily deal with)
    – cdeszaq
    Commented Dec 8, 2011 at 16:39
  • 5
    I don't this is a correct answer, even despite the random guy on xml.com who says it is. By changing the URL, you are suggesting that the underlying resource may be different, even though you know in advance that the underlying resource is always the same. Commented Jun 22, 2012 at 22:23
  • @mehasse - I get your point, but regarding your concern, you are suggesting that the underlying resource may be different, to whom is that suggestion being made? Any human looking at the url easily sees the implication. It won't really confuse anyone, in practice.
    – Cheeso
    Commented May 29, 2013 at 5:16
  • But if both the extension is specified in URI and Accept header exists. What is the precedence preffered? Commented Feb 24, 2018 at 11:25
17

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.

6
  • 7
    Wrong, according to REST. Each RESOURCE should only have a single URI - not each representation of that resource.
    – aehlke
    Commented Aug 19, 2009 at 14:55
  • 13
    You seem to take a very specific and biaised view of the notion of resource. Any thing that is useful enough to be addressable individually can be assigned a URI. If you need to make the distinction between two formats, you can "promote" them as resources. See W3C note on generic URIs and Roy's comments about what content-type negotiation should be used for: whenever and only when the distinction between the two media types is not significant.
    – SerialSeb
    Commented Aug 28, 2009 at 16:44
  • 4
    @Wahnfrieden Can you point us to the official source for your position on this? I've seen lots of discussion around this but never seen any concrete decision been written down. Commented Aug 28, 2009 at 18:05
  • 17
    Stumbled upon this again -- I have to take back what I originally commented, it was wrong. :)
    – aehlke
    Commented Feb 25, 2011 at 2:56
  • @serialseb Can you give some links to "See W3C note on generic URIs and Roy's comments about what content-type negotiation should be used for", please? and maybe even include it in the answer.
    – Jarl
    Commented Jan 23, 2014 at 8:17
8

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

6

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

1
  • May you provide link to proof this priority? Commented Feb 24, 2018 at 11:30
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

0
3

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...

2
  • 1
    Regards your PS: that thesis may be the place where REST was originally defined, but since it is not a standard, that doesn't make it the final authority on the concept as put into practice. Some questions, like this one, may not have a clear answer in that text, or later authors may make valid arguments to differ from its guidelines.
    – IMSoP
    Commented Jun 10, 2013 at 0:15
  • The problem about the Accept header in the HTTP request is that it is a list; giving the server a plethora of media types to choose among (which one to pick?). Further the Accept is not reliable in some very popular browsers
    – Jarl
    Commented Jan 23, 2014 at 8:13
1

Since very many RESTful URLs do not have an extension, you should/must base on Content-Type

edit: I don't mean this to sound as harsh as it does, more that you're going to have to pay attention to content-type and won't always be able to refer to extension

10
  • 2
    You're missing my point. See where it says "get"? That's the problem.
    – annakata
    Commented Aug 20, 2009 at 18:32
  • 3
    @annakata You're simply wrong - while including 'get' in the URI may be a hint that the developer doesn't know what he's doing and did not follow REST constraints, the name of the URI itself is not a violation of any REST constraint. It's merely an indication that something may be wrong, but you can name URIs however you like and still be RESTful.
    – aehlke
    Commented Aug 24, 2009 at 15:18
  • 3
    Just go read Fielding's dissertation and you'll find nothing about how URIs are supposed to be named or what they should look like.
    – aehlke
    Commented Aug 24, 2009 at 21:07
  • 2
    I'm not engaging in this comment tennis any more: post your own answer if you wish, otherwise this merely becomes trolling. And please don't cite bibles as authority when the world keeps evolving.
    – annakata
    Commented Aug 24, 2009 at 21:21
  • 9
    This is RPC: foo.com/getuser.php?id=99 This is REST: GET foo.com/user.php?id=99 (it's using HTTP method 'GET') The SAME URL can now be used with different HTTP methods: DELETE foo.com/user.php?id=99
    – opyate
    Commented Oct 1, 2009 at 12:40

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.