1

Possible Duplicate:
How to version REST URIs

I'm new to REST-ful API design, and I can't seem to find a consensus for how to implement API versioning in the REST-ful style. The possibilities I've come across include:

  • URL-based (eg. /myApi/version5/someCall)

    This approach works great for both servers and clients ... but it doesn't seem very REST-ful (urls are supposed to correspond to resources, and the API version really isn't a part of the resource)

  • Payload-based (eg. $.ajax({data:{version:5, ...)

    This approach works great compatability-wise, but:

    A) The server needs to actually parse the payload to determine the version (which tends to put the version-checking logic "deeper" in than it should be)

    B) Again, from what I can tell of the philosophy, this isn't very REST-ful (as I understand it, the data I POST should only be the data for the resource I want to create)

  • Header-based (eg. Accept application/json;version=5)

    This approach was suggested here, which I've found to be an excellent resource on how to make a REST-ful API. In this particular case however I keep running in to problems, as no matter what I do I can't seem to get jQuery to send the version in the header.

Now, I'm sure I can eventually solve the jQuery issue in approach #3 if I try, but it made me think that I might be going down the wrong road with header-based versioning; if I'm having trouble, it seems likely the consumers of our API would also.

So, when creating a REST-ful API, can anyone please explain which versioning approach:

  • A) will work with the best with other bits of technology (browsers, frameworks, etc.)

  • B) implement the "REST-ful" philosophy most faithfully

  • C) is most common (this one's not important on its own, but it does tend to be an indicator of the first two)

In other words, what's the best way to handle versioning in REST-ful APIs?

Community
  • 1
  • 1
machineghost
  • 33,529
  • 30
  • 159
  • 234
  • The first approach certainly seems the easiest to implement and understand, and the most popular in the wild. – Thilo Sep 12 '12 at 01:39
  • Have a look at: http://stackoverflow.com/questions/389169/best-practices-for-api-versioning – Pran Sep 12 '12 at 14:01
  • I'm going to mark my own question as a duplicate, since it seems pretty identical to "How to version REST URIs". Thanks everyone for the answers, and I definitely see the practical value of URL-based. However, this article (http://www.informit.com/articles/article.aspx?p=1566460), which was linked in the duplicate question, both convinced me to do header-based versioning and provided jQuery code that actually worked, so I'm going to go with that. I highly recommend that article to anyone facing the same question. – machineghost Sep 12 '12 at 16:52

2 Answers2

2

Solution 1 seems practical and simple. For your reference twitter(api.twitter.com/2) and linkedin(api.linkedin.com/v1) uses URL Based Versioning, Google Data(&v=1.0) uses Payload Based. My hands-on experience is in URL Based versioning.

If you want to do an analysis, check this api directory

basiljames
  • 4,777
  • 4
  • 24
  • 41
1

I would strongly suggest solution 1, it's clear and easy - not only that even StackOverFlow uses it: https://api.stackexchange.com/2.1/questions?order=desc&sort=activity&site=stackoverflow :)

endyourif
  • 2,186
  • 19
  • 33