Representation versioning. URI or Media Type?

Skip to first unread message

Joshua Graham

Jun 11, 2013, 1:22:12 AM6/11/13
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?


Jørn Wildt

Jun 11, 2013, 1:35:26 AM6/11/13
Mark Nottingham has a pretty good blog post on the subject:


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
For more options, visit

Josh Graham

Jun 11, 2013, 6:02:50 AM6/11/13
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
Reply all
Reply to author
0 new messages