Change and Communication Management

Implementation of a new OBIE Standard

This version is:

Published 9 months ago 21 Oct 2021

The OBIE Standard will continue to evolve to cater for regulatory changes, Open Banking roadmap requirements and approved changes (which may include adding new functionality, fixing defects, and errata). Where possible, OBIE will schedule new versions of the Standard so that all participants can plan ahead and build new APIs, this will reduce development and support costs for all participants, and increase adoption.

Other Journeys in ‘Change and Communication Management’.

Types of release and version numbering

Release type
Description
Version

Major

Significant breaking changes – which may require substantial implementation effort for ASPSPs and will cause existing TPP applications to fail) until TPPs also implement changes.

v1.0.0, v2.0.0, etc

Minor

Minor breaking changes – may require some implementation effort for ASPSPs and will cause existing TPP applications to fail until TPPs also implement change.

v1.1.0, v1.2.0, etc

Patch

Can include any non-breaking change, as well as errata and clarifications, which will not force TPPs to implement any changes.

v1.1.1, v1.1.2, etc

Release Candidate

Pre-release versions of any forthcoming patch, minor or major release. To enable OBIE to publish regular updates based on review and feedback.

v1.0.0-rc1, v1.0.0-rc2, etc

The version numbering above can apply to any individual component of the Standard. For example, the latest published API Specifications at a point time could be v3.1.1, and the latest published Customer Experience Guidelines (CEG) could be v1.2.0.

Within each, component, individual resources or functionalities can also change version numbers independently. For example, the latest Account and Transaction API Specification can be v3.1.1 and, within this, the /transactions resource can be v3.2.0. In this case, this resource has introduced a minor breaking change. And this may require one or more sections/sub-sections of the CEG to be updated to v1.2.1 or v1.3.0.

The above version numbering approach enables OBIE to introduce changes to the Standard incrementally, but at the same time reducing the need for ASPSPs and TPPs to make any unnecessary changes.

Introducing change

The following apply:

Together with the requirements for ASPSPs to notify TPPs of any changes (see section 5.5) any TPP will, except in an emergency, always have at least three months’ notice before being required to update their systems. 

Considerations

Dual running and deprecation

ASPSPs should support a minimum of two API versions in a production context, providing both versions were previously supported by the ASPSP, for a period of time long enough to ensure that TPPs have had sufficient time to successfully test the new version and migrate their applications and customers. Where an ASPSP is using OBIE’s Managed Rollout process, OBIE will be able to confirm when sufficient TPPs have migrated from the previous version to enable the ASPSP to reasonably demonstrate ‘wide usage’ of this new version. For all other ASPSPs, OBIE recommends dual running for at least six months for a major version, and three months for a minor version. Where an ASPSP implements an API for the first time, they will only need to support this one version to start with.

The ability to support two API versions allows TPPs to maintain existing integrations with the older version, and benefit from features and enhancements offered by the new version. Over time, TPPs will migrate all their applications to consume the new API version. Once migrated, TPPs should not access resources via the old API version (including creating, reading, updating or deleting).

Dual running of APIs requires a pragmatic approach to ensure that ASPSPs expose and support both API versions and to ensure that TPPs use these to migrate applications as intended, without unnecessary conflict.

The deprecation of unsupported versions is at the ASPSP’s discretion – based on usage metrics. However, the OBIE may recommend that any specified version (major, minor, or patch) should be deprecated at any time, and this should be implemented within three months of notification by the OBIE. This is to cater for critical defects, especially those relating to security. In exceptional circumstances it may be agreed by OBIE that support for a specified version is terminated earlier.

ASPSPs must not apply any measures to induce TPPs to adopt a new version of the APIs (e.g. rate limiting the older version while providing better performance on a newer version).

API credentials, consent and authorisation

API Credentials associated to an API should be version agnostic. Therefore, a TPP accessing v1.0, v1.1 or v2.0 should be able to use the same API Credentials across all available API endpoints.

It in the domain of the TPPs to manage PSUs consent and ASPSPs to manage PSU authentication in compliance with relevant regulations.

If there is a non-breaking change (e.g. an additional field is added to a permission/cluster) then this should be managed between the TPP and PSU and between the ASPSP and PSU respectively. Any long lived access or refresh tokens could then remain unaffected.

In the event of a breaking change (e.g. where a permission/cluster is added, removed or changed), then the PSU may be required to re-consent with the TPP and to re-authenticate with the ASPSP.

Backward and Forward Compatibility

The OBIE specifications will include details on which operations or resources are expected to be backward and forward compatible across versions. It is expected that:

If an ASPSP is planning to release a new API version that does not follow the expectations above (e.g. does not support forward compatibility for AISP resources) this should be communicated to TPPs (e.g. via the OBIE’s ASPSP Calendar).