It seems to me that approach #1 could work, since the resource is identified by the URI and therefore doesn’t have to be part of the media type. On the other hand, it feels funny for a media type to be so loosely defined that it could be applied to two representations that looking nothing alike.

http://aspnet.uservoice.com/forums/147201-web-api/suggestions/2620003-use-order-of-entries-in-the-accept-header-for-entr?tracking_code=519af301292bc3a981a99d51a6231ba5

I believe they are being short sighted, but the best way to guarentee you get the best possible representation is to use the q factor.

Hopefully others will raise this with Microsoft as well… I tried here also:

http://forums.asp.net/t/1771514.aspx/1?Accept+type+ordering

So in the beginning I started to with
/customer/{id}/contact

and now I have a
/customer/{id}/contacts
/customer/{id}/contacts/{number}
I also repurposed my original contact URI as the “primary contact”, but I did not like it so I also created a:
/customer/{id}/primaryContact

There’s always http redirects…

===>
GET /customer/22/contact
Accept: application/vnd.myapp-v1+xml
<===
301 MOVED PERMANENTLY
Location: /customer/{id}/primaryContact
===>
GET /customer/22/primaryContact
Accept: application/vnd.myapp-v1+xml
<===
200 OK
Content-Type: application/vnd.myapp-v1+xml


The Web’s approach introduces a triangle of methods, document types and URLs that each evolve as separately moving parts.

I don’t think the architecture of the web ever considered “versioning” as a key design requirement. It kind of “works” with web pages. As soon as you live this trivial use case for “connected systems” I can only see issues.

A client issues a GET request with an Accept indicating the understood formats. The server knows how to pack the returned information into at least one of these, and responds.

I’d like to point out that in a true versioning strategy, the server should respond based on its own version. So if client 2.1 calls server 2.4, the response should be in 2.4 format. This is why forwards compatibility is so valuable because it prevents the server to have to operate all kinds of minor versions. Imagine a situation where you have 3 major version and 10 minor in each. How many versions are you going to operate/maintain? With forwards compatibility you only operate/maintain 3.

sorry, I don’t see the light, and again, I am trying. I live in a world where reuse, reliability, security (authorization), predictability… are the norm. I see so many holes in this approach that I don’t see why I should spend any time investigating it. Now if your context does not require so much security, reliability, predictability… and you really need the kind of scalability that REST can give you, great, I am all for it. But please, don’t mix and match these two context, as I mentioned you are creating a losing proposition for everyone involved.

You aren’t actually versioning a service or a resource with this content-type setting. You are setting the version of the document type.

The model here is a heterogeneous one. The assumption is that there might be five different server implementations and twelve client implementations, all with various kinds of jargonization (version forking as well as incrementing) to their protocols and document types. Any and all of these might have been upgraded or left at their original version over the lifetime of the architecture. The Web’s approach introduces a triangle of methods, document types and URLs that each evolve as separately moving parts.

Document types use must-ignore to encourage a certain fuzzyness of version that supports upgrade and some jargonization of a document type. For example, I could use a standard document type with a bit of extra information inserted for good measure. It will be understood in a limited context, but the rest of the document will still be understood universally. If I really exhaust the evolution path for a particular document type I come up with a new one an rely on content negotiation as per Peter’s approach.

In a true REST architecture both methods and document types are controlled. There is a limited number of ways that a particular schema of data is allowed to be encoded into, and every way that exists at a given time can be expected to be understood by the document recipient.

A client issues a GET request with an Accept indicating the understood formats. The server knows how to pack the returned information into at least one of these, and responds. The client processes the document, extracting information according to its needs. Communication is achieved, and with the resource that the client intended. Versioning takes second place to heterogeneous evolution.

See also my article on REST Rewiring: http://soundadvice.id.au/blog/2008/04/18#rest-rewiring