Versioning Principles

FNZ aspires to follow the guiding principle of API Evolution:

API Evolution is the concept of never breaking your contracts until you absolutely absolutely have to, then when you do you manage that change with sensible warnings to clients. It is not about making arbitrary changes and breaking stuff.

- Phil Sturgeon (https://apisyouwonthate.com/blog/api-versioning-has-no-right-way#api-evolution)

Where possible we will endeavour to make changes in a manner that is additive and/or backwards compatible.

In the exceptional circumstances where a breaking change is introduced to the API, a new dated version is released. To avoid breaking your code, we don’t change your version until you’re ready to upgrade.

We have a deprecation policy to ensure consuming applications are duly notified and given sufficient opportunity to adapt to these changes.

Versioning Strategy

We utilise date-named versions that correspond to our API changelog and the date in which the changes were released (e.g. 2021-09-04).

You may also notice a path fragment in the API URIs, e.g. v1 in https://api.sandbox.tapico.io/v1/payment-instructions.

We have no plans to make use of path-based versioning, but have incorporated it from the outset to avoid disruption to applications should we wish to utilise it in the future. Any such plans will be communicated well in advance and we will consult our community before proceeding with such a change.

Breaking Changes

Versions are only incremented in response to breaking API changes.

Examples of such changes (not an exhaustive list):

Renaming a request payload property / query string param.
Removing a response payload property.
Removing a request payload property / query string param.
Making a previously optional parameter mandatory / Add a new mandatory field.
Changing the data type of a property.
Changing API endpoint path (Old and new paths will be simultaneously supported for a duration of time, see: Deprecation Policy)
Removing an API endpoint

Version Selection

When you create a new Application it's automatically configured against the most recent API version by default. If a new version of the API is released, the version set against your Application won't automatically change.

There's two mechanisms for controlling the selected API version if you need to change it from the default:

Application Default Version Selection

Applications can select the default API version in the application wizard, specifically in the “Open Wealth” section, which becomes available after subscribing to the Open Wealth Service Pack.

This is the version that takes effect in the absence of an explicit selection via Tapico-Version HTTP request header.

NOTE: When updating the application default version, any existing access tokens issued for the application will still reference the previous default. The updated version will be reflected in any new tokens issued.

HTTP Header

Applications may optionally send an HTTP Header Tapico-Version in their requests to specify the API version on a per-request basis. Check out our API changelog for a list of valid versions.

Doing so will override the default application version for that particular request and provides some flexibility for applications to employ incremental or divergent upgrade paths for the different APIs it consumes.

Example:

curl --location --request POST 'https://sandbox.tapico.io/api/v1/payment-instructions' \
--header 'Tapico-Version: 2021-09-04' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ...' \

Deprecation Policy

We will continue support for deprecated APIs or API components (fields, parameters etc.) for at least 6 months from the point of announcement.

Deprecations will be notified via our changelog, and also labelled in our Open API spec via the deprecated keyword.

Versioned API Documentation

These API docs themselves will also be versioned when a breaking change is introduced into the API. In the top left hand corner is a version drop down which can be used to swap to older versions of the API docs/guides.