Re: API versioning

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


Hmm.  I wouldn't say I'm using a different "language", I'm very explicitly using the Content-Type to negotiate the media format (say "vnd.example.com.order+json").  I can imagine a breaking change to the representation of the resource at the URI api.example.com/order/[order-id] that can be represented by returning a Content-Type of "vnd.example.com.order+json;version=2" or something similar.  Similarly, clients can request that specific version of the resource with the Accept header set correctly.

This seems to be a recommended practice that I've encountered in reading about RESTful implementations.

> 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.


On 2013-01-07, at 10:37 PM, Eric J. Bowman wrote:

> "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