API Endpoint Versioning Methods: Sub-domain or Directory?

Adam DuVander
Aug. 21 2013, 09:00AM EDT

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.

Sub-domain

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:

  • api
  • ws
  • services
  • webservices
  • secure
  • search
  • apis
  • trial
  • app
  • dev

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.

  • apiv1
  • api-v1_1
  • api2

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.

Directory

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:

  • /api
  • /services
  • /rest
  • /v1
  • /ws
  • /webservices
  • /cgi-bin
  • /api.php
  • /1.0
  • /service

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****:

  • /v1
  • /V1
  • /v1.0
  • /V1.0
  • /1
  • /v1api

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.

Popular Version Numbers

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
0 4
1 103
2 27
3 4
4 2
5 0
6 68

Keep in mind this is a sampling. ProgrammableWeb does not have endpoint data on every API.

Other Methods

There are certainly other methods of API versioning. Here are a couple--be sure to mention others in the comments.

Querystring

Really just an altered method of the version in the directory puts it instead in the query. The old Bing Maps, for example, stored its JavaScript at http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.1

HTTP Header

Another method is to use an HTTP header or, similarly an application MIME type. GitHub does the latter.

Date of API Release

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.

Adam DuVander is Developer Communications Director for SendGrid and Contributing Editor of ProgrammableWeb. Previously he edited this site and wrote for Wired. You can follow him on Twitter.

Adam DuVander Hi! I'm Developer Communications Director for SendGrid and former Executive Editor of ProgrammableWeb. I currently serve as a Contributing Editor. If you have API news, or are interested in writing for ProgrammableWeb, please contact editor@programmableweb.com Though I'm a fan of anything API-related, my particular interest is in mapping. I've published a how-to book, Map Scripting 101, to get anyone started making maps on websites. In a not-so-distant past life I wrote for Wired and Webmonkey.

Comments

Comments(2)

There's also the combined approach. I've produced designs that place the major version in the Directory (/v1) and the minor version in the media-type (application/foo;v=2). The combined version is then 1.2.

Of course there are those that say API versions are an anti-pattern but probably best not to kick that off again :)