Re: API versioning

Keith Hassen wrote:
> 
> This seems to be a recommended practice that I've encountered in
> reading about RESTful implementations.
> 

Perfectly good HTTP API practice; REST, not so much.  The point of
media types is to provide loose coupling based on shared understanding
of how the representation is to be decoded.  Not tight coupling based
on interpreting the content of the representation.  I've never seen an
order API that couldn't be represented as HTML; despite any number of
variations on this theme (or versions within), the media type doesn't
vary between more order APIs on the Web than I can count.

REST has no notion of resource "type" let alone of exposing same on the
wire, so I've never understood why this solution is so prevalent in REST
discussions.  Just media types, which are agnostic as to what "type" of
resource is being represented (with rare exceptions as parameters).

>
> > Anything else is up to the user-agent to work out.  This is actually
> > easier for m2m than h2m; a v1 m2m client should already ignore any
> > hypertext it doesn't understand, rolling out v2 can then re-use any
> > non-deprecated bits of the API already present plus the new stuff,
> > and ignore the deprecated stuff.  Can't it?
> 
> Not always, at least not in my experience. :)  I have found that
> while breaking changes don't happen often, they *do* happen.  Add to
> this the possibility of different types of API consumers that start
> off implementing your APIs the same way, but slowly (or rapidly!)
> diverge over time.  In some cases new resources (and thus new URIs)
> will suffice, but in other cases what we are doing is very
> specifically *evolving* the resource representation to accommodate
> new requirements.
> 

Then design for graceful degradation (or progressive enhancement) using
client-side feature detection.  Just saying there's no need to swing
the conneg hammer to turn this particular screw.

-Eric