Representation versioning. URI or Media Type?

63 views
Skip to first unread message

Joshua Graham

unread,
Jun 11, 2013, 1:22:12 AM6/11/13
to restinp...@googlegroups.com
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

unread,
Jun 11, 2013, 1:35:26 AM6/11/13
to restinp...@googlegroups.com
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

unread,
Jun 11, 2013, 6:02:50 AM6/11/13
to restinp...@googlegroups.com
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
Forward
0 new messages