Re: API versioning

"erewh0n" wrote:
>
> I'm aware of the recommendation to use the content-type header for
> specifying version information...
>

If you're using a whole different "language" to describe your API each
time it changes, you're missing the point of REST...

>
> So for example if we versioned an API with api.example.com/orders/v1
> and api.example.com/orders/v2, it is straightforward to route requests
> for v1 to one set of web servers and route requests for v2 to another
> set of web servers.
>

Likewise, if you need a whole 'nother server farm each time your API is
modified...

>
> This is also true in-code, where URI mapping semantics are first-
> order concerns for many libraries (e.g. using Web API or ServiceStack,
> etc, it is straightforward to map URIs to controllers or contracts).
> 

Aha!  HTTP frameworks do encourage solving problems at the protocol
layer.  What they aren't much good for, unfortunately, is thinking in
hypertext.  I don't want to say there's no versioning in REST, in fact
if I PUT an existing image to my server, the old image is renamed not
removed; there's a "versioned" API inherent in this strategy.

As to API versioning, do just that, version your hypertext API -- not
your URLs, your conceptual mappings aren't changing.  Neither should
your media type -- I mostly use XHTML to define APIs, that's as detailed
a description of the actual API as intermediaries need in order to
participate in the communication (which they won't do if you're just
"re-labeling" XHTML as custom, versioned media types to conneg around
proper hypertext API design).

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?

-Eric