[Catalyst] Re: General API question: REST + SOAP

[Aristotle Pagaltzis]

* Trevor Leffler <tleffler at uw.edu> [2011-04-06 18:50]:
> Hi, I've also seen the use of HTTP request headers for
> specifying service API minor versions (and other bits).  In
> particular, EBay comes to mind; they use v1, v2 in the
> end-point plus an X-EBAY-SOA-SERVICE-VERSION header.
>
> http://developer.ebay.com/DevZone/finding/Concepts/MakingACall.html#callstruct

This is a very bad idea. No matter what problem you have,
a custom HTTP header is very nearly certainly the wrong solution.
For API versioning it definitely is.

Putting the version in the URI is the right approach – if in fact
you even need an explicit version. (You can always switch to
a different URI space no matter whether you made a provision for
it using a version number in the URI or not.)

Of course eBay didn’t have a lot of options, being that their API
is SOAP-centric (even though they now support non-SOAP options).
So don’t make their mistake: don’t use SOAP. If you inescapably
have to support it as an option, then at least don’t design your
API from its point of view.

Regards,
-- 
Aristotle Pagaltzis // <http://plasmasturm.org/>