API Versioning Tip

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:


can be exported to your web site:

/var/www/api/ ← this is your “tags” dir

and result in URLs like this:


Other tips and suggestions? Share them in the comments.