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.
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.
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.[…] API Versioning Tip […]
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.
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.
[…] 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 […]
[…] 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 […]