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.
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:
To be version-aware, your app should declare the range of versions that it supports, for each developer's APIs, at developer.talentappstore.com.
For example your app might declare that it supports:
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.
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.
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.:
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:
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.