Toggle document index


Over time, API definitions can change.

As long as your app is well-coded (e.g. is resilient to non-breaking changes, such as unrecognised properties appearing in a request body) then it should keep working, even if you don't make it version-aware, so long as the APIs it produces and consumes only undergo non-breaking changes.

However if your app uses APIs that have breaking changes, and you want to preserve compatibility with previous versions (rather than just track the latest versions) - or if you just want to err on the side of safety and reliability - then you'll need to make your app version-aware.

About version numbers in TAS

TAS allows APIs to be designated a version number of the form major.minor, e.g. 1.02.

The version number is allocated by the developer who owns the APIs, and applies to all of their APIs (i.e. there is no per-API versioning).

Its up to each developer how they allocate version numbers for their APIs, but for our own (Aotal's) APIs, we follow this approach:

  • it's a marketing decision to change the major number
  • any breaking change to an API will always +1 the minor
  • the minor can also +1 for significant non-breaking changes

Making your app version-aware

Declaring the API versions your app supports

To be version-aware, your app should declare the range of versions that it supports, for each developer's APIs, at

For example your app might declare that it supports:

  • versions 1.02 to 2.13 for the APIs from the developer "tas"
  • a different version range for some other developer's APIs

NOTE: The UI described above to declare your app's version range as above is not yet available in TAS. For now you should specify your app's version range in text within its description, so that other developers can read it and manually set the version when they consume APIs produced by your app.

Producing APIs

When your version-aware app produces APIs, it should check the requested version (within the Content-Type header), and behave accordingly.

For example, for the APIs from the developer "tas", the header might look like this:

Content-Type: application/vnd.talentappstore.tas-tenant-apis+json;version=2.01

This tells your app that the consumer wants the behaviour of version 2.01.

If no version is passed, your app should use its latest behaviour (whatever version that is at).

Whichever version you do decide to use, you should return it within the ContentType header in the API response.

Consuming APIs

When your version-aware app consumes APIs, usually you will want to consume them at the highest version supported by both your app and the producing app.

TAS provides new details within the GET /routes API call that you can use to determine this, e.g.:

  1. your app is consuming the GET /jobs API (from the developer "tas")
  2. your app supports versions 1.02 to 2.22 for the APIs from developer tas
  3. the tenant has installed the Big Red ATS app, which produces that API
  4. the Big Red ATS app supports versions 1.01 to 2.05 for the APIs from developer tas

In this example, when you call GET /routes, you will get back:

    "consumingAppInstall": {
    "consumedApi": {
    "producingAppInstalls": [
            "tenant": "acme",
            "app": "bigredats",
            "maxCommonVersion": "2.05"

Now, when your app consumes the GET /jobs API, you can:

  • set up the correct request data for version 2.05
  • consume the API, passing across the ContentType header, with a version of 2.05.

If the producing app has not declared the API versions that it supports, then the maxCommonVersion field will not be present. In this case, don't pass any value for version when you make the API call, and the producer will just use its own default behaviour. e.g. pass a ContentType header like this:

Content-Type: application/vnd.talentappstore.tas-tenant-apis+json

NOTE: The new GET /routes response described above is not yet available in TAS. For now you should review the documentation of the app you are consuming APIs on, and manually set the version in your API requests.