You say that content negotiation is “not when you request X1 and get JSON, and then you request X2 and get XML” — not according to RFC 2295 §4.6 (Retrieving a variant by hand), where the consumer requests different resources in order to receive different content types.

It seems that we agree on something, though: only a few people really read RFCs these days.

Anyway, thanks for the interesting discussion.

I stick to what I wrote before, and please don’t assume that nobody reads the RFCs, albeit I reckon it is only a few.

FWIW I still think you’re missing the point – content negotiation is when you request X twice, and one time you can get JSON, one time you can get XML. Not when you request X1 and get JSON, and then you request X2 and get XML. It’s irrelevant that the resources map to the same entity, it is still resource*S*

But let’s leave it to each and every potential reader to make up their mind.

I appreciate your comment and clarification, but I didn’t miss Darrel’s point — I even agreed with him that the first two techniques were presented because many APIs rely on them to provide content negotiation.

Now, replying to you, if you read RFC 2616 §12.1 (Server-driven Negotiation) carefully, you’ll notice the following phrase:

“However, an origin server is not limited to these dimensions (request-header fields) and MAY vary the response based on *any aspect of the request*, including information outside the request-header fields or within extension header fields not defined by this specification.” (bolds and contextual information added by me)

Also, by reading RFC 2396 §1.1, you’d know that a “resource is the conceptual mapping to an entity or set of entities, not necessarily the entity which corresponds to that mapping” and by reading RFC 2295 (Transparent Content Negotiation in HTTP) §4.6 (Retrieving a variant by hand) you’d know that the “user agent can use this list (of variants) to make available a menu of all variants and their characteristics to the user.”

So, negotiation can assume many different forms, including one where the consumer directly requests a variant of the resource obtained from a previously published list (the API documentation, in our case).

— For future readers —

For what it’s worth, you’re missing Darrel’s point. The first 2 ways to “provide Content Negotiation” – query and “extension” – are not about negotiation. If you have a static web server, you request a file with extension .json .png etc. No negotiation happens. Same with the query param. You request “http://example.com/x?format=json” – that’s the URI of the “document” – the atomic resource URI. The document you requested it’s not “http://example.com/x”

Negotiation is a give&take not all-or-nothing process. And that only happens for “the 3rd way”. The client can say “Accept: application/json, application/xml” and the server can reply with either of the two, or with text/html, and in all 3 situations the negotiation succeeded, or with 406 Not Acceptable – negotiation failed.

Thanks, Jorge!

Although XML promised a huge number of advantages, reality is that most Web APIs are not using it.

The advantages of JSON over XML make it a popular choice nowadays. I recommend you read this interesting piece comparing both formats: http://www.json.org/xml.html

On motivating the need/usefulness to support multiple data-formats (a.k.a. resource representations)…but should make a stronger point in defence of XML (not only “backward compatibility”).

If the client is not JavaScript, in principle, odds should favour XML over JSON (since its a more complete and rich technology ecosystem — e.g. more expressive syntax, namespaces, XSLT transformation, XPATH selector, better and more libraries, etc.).

However, because most apps and business models build these days are really around webapps, we actually see a tendency to support mostly JSON in HTTP based APIs (flanking the original spirit layed down in HTTP1.1 spec).

Maybe because people think its easier, faster, and cheaper to support only one format. This is the case is app rely a lot on manual marshaling, but not so if automated marshaling is put in place.

Cheers, Jorge.

I disagree. In the context of Web APIs it’s important to show different options because some APIs are implementing them.

For example, Highrise API uses resource extensions as a mechanism to negotiate different formats (https://github.com/37signals/highrise-api#alternative-formats). They support XML as a standard but they can respond with VCF on some resources related with contacts.

Strictly speaking, HTTP Content Negotiation doesn’t involve GET parameters or resource extensions. As I wrote on the article “the best approach is to follow the standards”.

Having clients construct a URI with a format=x is not really content negotiation because there isn’t really any negotiation going on. All that is happening is that you are providing multiple resources that expose different media types. This is necessary when doing agent driven negotiation, but in itself, it is not negotiation.

When discussing conneg it is important to consider caching issues and it is worth explaining how different options can be presented to a client to enable agent driven negotiation.