It’s an inevitability of creating APIs is that at some point you’ll need to make a breaking change. No matter how much you attempt to consider the future, unforeseen forces can disable your best intentions. If you have a versioning plan, you’ll be one step ahead as you push out a new version of your API. There are many thoughts on API versioning, but this post will focus on data from the ProgrammableWeb directory, specifically with the two most common methods: the endpoint sub-domain or directory.
Hosting your API on a sub-domain is a very common practice. One of the big advantaged of using a sub-domain is that you can host your API on different servers from your main site. In fact, API management services usually require a sub-domain to route calls, most often relying on a private service the API provider makes available without rate limits.
The most common API sub-domains:
Hosting an API on a sub-domain is not the same as versioning on the sub-domain. In fact, one can version at the directory level while hosting on a sub-domain. While that’s the most common combination, there are examples of using a sub-domain to version.
Again, this method is much less common, but it does have the added benefit of simply changing the base domain, though including a directory in the base URL is trivial.
Hosting an API in a directory is the most common method, with the highly guessable /api as the most likely endpoint. Here are the most common directories:
As you can see, sometimes a versioned directory is the root. However, in other circumstances, it sits off another directory, such as /api/v1 (the most common). Check out the variations of directory versioning with a first version as an example, in order of popularity****:
A single version digit, or major version, occurs most often in ProgrammableWeb’s data. The common software practice of decimal notation sometimes extends into API versioning. Most of the time there are minor changes for minor versions, though Twitter’s version 1.1 is a notable exception.
Most APIs with versioning in a directory are still on the first version. Here’s a run-down of APIs by major version level, consolidating the many variations:
|API version||API count|
Keep in mind this is a sampling. ProgrammableWeb does not have endpoint data on every API.
There are certainly other methods of API versioning. Here are a couple–be sure to mention others in the comments.
Another method is to use an HTTP header or, similarly an application MIME type. GitHub does the latter.
Twilio uses a date as a way to tie to a specific API release. Twilio’s latest release as of this writing has a base URL of https://api.twilio.com/2010-04-01/.
Got other API versioning ideas? Let us know in the comments.