You create APIs because you want people to build to them. When people build to your APIs, they need to continue working – even if/when the APIs need to evolve over time. The best way to do this is to build API versioning right into the API URLs themselves.
Yes: api.example.com/1.0/command
No: api.example.com/command
Assuming your API code is set up in source control using a standard trunk, tags, branches structure, an easy way to set this up is to simply check out (export, etc.) the tags directory structure to your web server. This ties the versions in the URLs directly to the tagged versions in your code.
Source code structure:
svn.example.com/api-code/tags/1.1
can be exported to your web site:
/var/www/api/ ← this is your “tags” dir
and result in URLs like this:
http://example.com/api/1.1/command
Other tips and suggestions? Share them in the comments.
Popularity: 1% [?]
gslin adds this Comment:
If you use svn, don’t put “.svn” directory into webroot, a better way is to use deploy utility to spread your code, don’t use “svn co” in server side directly. Usually keep .svn away from webroot will enhance security.
If you insist to put .svn into webroot for some reasons. Avoid to use .htaccess to deny outside access as only ACL. Also remember to use another username & password to do checkout. This can avoid username and password leaking when .svn be accessed. It’s because when people trying to upgrade from Apache to lighttpd or nginx, they *often* forget to add configuration to deny .svn directory.
Putting all tags directory into webroot is not a good habit, I think. Sometimes you will use VCS to create a temporily branch to do some work, which causes security risk.
A better approach might be to use hg/git, they only put .hg/.git into root directory of working repository. And remember to use deploy utility, most utility can set filter to avoid some directories and files be deployed.
Back to the origin subject, delicious API and Amazon Web Services API seems good examples. The first one use “v1″ as version path, and the later one use release date /2008xxxx/, fixed version number /1.0/, and /latest/ to keep different version (and different level) of API. I believe this already an acceptable solution.
December 13th, 2009 at 2:01 pm
Alex adds this Comment:
Blocking access to .svn directories is trivial:
RedirectMatch 404 /\.svn(/|$)and the benefits of managing your web sites with live checkouts are too numerous to detail here.
Temporary branches should be made in the branches/ dir, not the tags/ dir.
If this is a sticking point to someone, an
svn exportwould accomplish the same thing in this case.December 13th, 2009 at 7:02 pm
links for 2009-12-13 « burningCat adds this Pingback:
[...] API Versioning Tip [...]
December 13th, 2009 at 7:03 pm
Joseph Scott adds this Comment:
Agreed, I like the idea of having the version number right in the URL. One additional problem this approach can bring is getting clients that use the APIs to transition to updated versions. Not a deal breaker, but something that should be considered.
December 14th, 2009 at 8:03 am
Alex adds this Comment:
That’s an excellent point – I was thinking about this as well. I’m considering adding a couple of properties to the return values of the API – something along the lines of:
- current API version
- API version deprecation date
Ideally the old API versions could live forever, but I also realize that isn’t always realistic.
December 14th, 2009 at 8:11 am
How to Avoid “API Slamming” and the “API Treadmill” adds this Pingback:
[...] are some simple solutions. Alex King shows how to implement versioning with a simple modification to the API endpoint: When people build to your APIs, they need to continue working – even if/when the APIs need to [...]
January 6th, 2010 at 12:27 am
How to Avoid “API Slamming” and the “API Treadmill” | Open Source Blog adds this Pingback:
[...] are some simple solutions. Alex King shows how to implement versioning with a simple modification to the API endpoint: When people build to your APIs, they need to continue working – even if/when the APIs need [...]
January 6th, 2010 at 11:01 am