How to request content types (XML, XHTML, JSON, etc.) from RESTful services?

How should web services determine the format of a response to a client? Or how does a client ask for XML, XHTML, or JSON?

This question is becoming more pressing as UW web services such as the Student Service, Financial Service, and ID Card Service begin to expand their format offerings. These services began with just XHTML, largely due to how conveniently it renders in a browser, but a growing number of developers have vocalized their desire for a more terse XML format that works with their libraries and tooling that read XML, but not XHTML.

In our recent discussion of this issue on the ROA Technical team, we considered several options for how to request content type:

  1. URI query string

    GET /books/12345?format=xhtml HTTP/1.1
  2. URI file name extension

    GET /books/12345.xhtml HTTP/1.1
  3. Content negotiation using the Accept header

    GET /books/12345 HTTP/1.1
    Accept: application/xhtml+xml

There is plenty of debate about which is the better approach.

In their book, Richardson and Ruby prefer the explicit URI specification over the content negotiation:

Unlike humans, computer programs are very bad at dealing with representations they didn’t expect. I think an automated web client should be as explicit as possible about the representation it wants. This almost always means specifying a representation in the URL (RESTful Web Services, 94).

We lean that way, too, and prefer the URI file name extension option. It’s intuitive from all of our Web browser years; it’s simple; and it’s easy to test in a browser (you don’t have to monkey with headers).

We also think services should expose a default extension-less URI that either redirects to the .xhtml/.xml resource or returns a location header to it.

GET /books/12345 HTTP/1.1


Even though we think that the URI file name extension option is preferable, we’re not too religious about it. As long as the contract is made clear, any of these three methods are acceptable.

Let us know what you think.

3 thoughts on “How to request content types (XML, XHTML, JSON, etc.) from RESTful services?

  1. Matt H

    I’m a fan of the explicit file extension in the URI… seems like the cleanest approach to me (and I’m a Rails guy, so that’s what I’m used to). Your default extensionless URI is also a great idea. I would expect that default URI to load up the xhtml version of the resource, for two reasons: xhtml is already what users expect as your “default” format, and xhtml will render in a browser for human consumption. Seems like a default format should render something that a human can understand.

Comments are closed.