restarchitecturerestful-architecture

REST API versioning - popular API's

I am trying to gather information about REST versioning. When I check forums the most preferred one seems to be to use Accept headers. However if I check APIs of StackExchange, Google, Twitter, Yahoo, Instagram and eBay they all use versioning through URI.

I can't find why they prefer this way over HTTP headers. I would like to know the facts, not opinions. Can anyone help with this?

Solution

  • There really is no 'right' way to do api versioning in REST. The best article I've read explaining the different 'wrong' ways to do it is this one by Troy Hunt: Your API versioning is wrong, which is why I decided to do it 3 different wrong ways

    To quote the article, he writes about three options:

    1. URL: You simply whack the API version into the URL, for example: https://haveibeenpwned.com/api/v2/breachedaccount/foo
    2. Custom request header: You use the same URL as before but add a header such as api-version: 2
    3. Accept header: You modify the accept header to specify the version, for example Accept: application/vnd.haveibeenpwned.v2+json

    In the comments and discussion, a few more techniques are identified:

    1. hostname: e.g. https://v2.api.hostname.com/resource
    2. Query String: e.g. https://api.hostname.com/resource?api-version=2.0
    3. A variant of the accept header: application/vnd.haveibeenpwned+json; version=2.0

    You wrote:

    I would like to know the facts, not opinions.

    Unfortunately there is no such thing as facts here - for all the reasons above, any decision is based on the opinion of the person responsible.

    So, while there is a lot of argument one way or the other (see also this Best practices for API versioning? and other references Troy links to) I believe many of the 'big' services converge on the URI approach for one simple pragmatic reason:

    It is the simplest to understand and implement for a novice client developer.

    These services want to make it as easy as possible for the most number of client developers to interact with their api, with as little support required as possible - many of whom will have only been inspired to code at all by the desire to interact with this services' api.

    Manipulating a string to construct the uri is a fairly trivial task in most client languages, and many novice developers will possibly have never heard of an accept header. So, you could consider it designed to suit the lowest common denominator of developer.