19242Re: [rest-discuss] API versioning
- Jan 7, 2013"erewh0n" wrote:
>If you're using a whole different "language" to describe your API each
> I'm aware of the recommendation to use the content-type header for
> specifying version information...
time it changes, you're missing the point of REST...
>Likewise, if you need a whole 'nother server farm each time your API is
> 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.
>Aha! HTTP frameworks do encourage solving problems at the protocol
> 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).
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?
- << Previous post in topic Next post in topic >>