API Endpoint Versioning Methods: Sub-domain or Directory?

Adam DuVander, August 21st, 2013

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.

Both comments and pings are currently closed.

2 Responses to “API Endpoint Versioning Methods: Sub-domain or Directory?”

August 22nd, 2013
at 8:04 am
Comment by: Todd Fredrich

Nice overview of API versioning, Adam. We had a great discussion about versioning at the API Craft 2013 conference in Detroit, July 29-31. An outline of the discussion is here: https://github.com/apicraft/detroit2013/wiki/API-Evolution

Additionally, I followed up with a blog entry on versioning: http://toddfredrich.com/rest-api-versioning-good-bad-or-ugly.html

Thanks,
–Todd Fredrich

August 23rd, 2013
at 6:10 am
Comment by: snow6oy

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

Follow the PW team on Twitter

ProgrammableWeb
APIs, mashups and code. Because the world's your programmable oyster.

John Musser
Founder, ProgrammableWeb

Adam DuVander
Executive Editor, ProgrammableWeb. Author, Map Scripting 101. Lover, APIs.