Representation versioning. URI or Media Type?

[Joshua Graham]

Picture a nice, RESTy remote API where we use Postel's Maxim to reduce the amount of version-coupling a resource's XML and JSON representations has.

When the time eventually comes to dramatically alter the structure in a way that breaks compatibility, most APIs I've seen go straight for putting the version number in the URI path (eg "/context/v1/resource" or similar). However, I've also seen the use of media type to indicate version (eg Content-Type: application/json+hal+v2).

I feel the URI is "easier" and certainly more obviously apparent. I also feel the media type is a truer reflection of reality -- it's the *same resource*, just a *different representation*. If it was truly a different resource (just very similar to another), then I'm all for the URI changing.

Which do you prefer (as a consumer, producer, developer, documenter, etc), and why?

TIA,

Josh

[Jørn Wildt]

Mark Nottingham has a pretty good blog post on the subject: http://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown

/Jørn

--
You received this message because you are subscribed to the Google Groups "restinpractice" group.
To unsubscribe from this group and stop receiving emails from it, send an email to restinpractic...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Josh Graham]

It is indeed, as is the follow up, although I think he gets weaker (pragmatic?) on using HATEOAS. Also the Home Document spec is interesting although I am a bit perplexed at the preponderance of URI Templates in it and HAL and the like.

Thanks for the pointer Jørn!

----------------------------------

From the phone