Loading ...
Sorry, an error occurred while loading the content.

19242Re: [rest-discuss] API versioning

Expand Messages
  • Eric J. Bowman
    Jan 7, 2013
      "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

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

    • Show all 13 messages in this topic