[rest-practices] Versioning

[Mark McLoughlin]

On Mon, 2010-04-26 at 10:43 -0400, Bob McWhirter wrote:
> Isn't this where the other week's discussion on content-types, content  
> negotiation, and Accept: headers figure in?  The API and the model of  
> the resources is one-in-the-same, really, no?  The "API" is just a  
> root synthetic collection or object, sometimes, versionable like any  
> other model entity using content-type.

Yes, yes and yes :)

To be clear - I'm only talking here about incompatible versioning of
incompatible revisions of the interface. I don't think we need versions
for compatible revisions. And we also should very, very rarely have
incompatible revisions.

My understanding of the previous discussion was that we were leaning
towards not using media type versions for incompatible revisions e.g.

  https://www.redhat.com/archives/rest-practices/2010-April/msg00008.html

  What I've read is that a different URL scheme might be preferable for 
  clients that are not able to participate in HTTP content negotiation
  (like a browser). If you're following the guideline of not exposing
  your URL schemes and instead using links, then things actually become
  simpler for the client as it doesn't have to set any Accept headers.

  https://www.redhat.com/archives/rest-practices/2010-April/msg00017.html

  But I tent to think that content negociation makes things way harder
  (and fragile) than they should. A versioned URI space if you really want
  to decouple different version support is the simplest IMHO.


Given that we're talking about (hopefully) very rare incompatible
changes, I much prefer the simplicity of doing the versioning in the
URIs.

This is one of the reasons I wanted the style guide thing - so we can be
clear whether we're actually coming to agreement on things or not :-)

Cheers,
Mark.