Implementation of a new OBIE Standard

The OBIE Standard will continue to evolve over time to cater for potential regulatory changes/clarifications, agreed 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 to this plan, this will therefore reduce development and support costs for all participants and increase adoption.

Types of release and version numbering

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:

• It is up to ASPSPs to take their own position of which version of each component of the Standard they chose to implement in order to meet both regulatory and commercial requirements.
• As per RTS Article 30(3), ASPSPs must publish technical specification documentation for their dedicated interface, at least six months before 14 September 2019 or at least six months before the target date of the market of the dedicated interface. In practice, this means that ASPSPs should publish details of exactly which version/versions of each component are supported by their dedicated interface.
• As per RTS Article 30(4), ASPSPs must give TPPs at least three months’ notice of any change to the technical specifications. In practice, this means that ASPSPs must give such notice if they are planning to introduce any updates to any component of the Standard, regardless of whether these are major, minor or patch updates. Any change may be implemented in an emergency situation (e.g. in the case where there is a security issue) without such notice, and in such situations ASPSPs must document emergency situations where changes are implemented and make the documentation available to competent authorities on request.
• As per RTS Article 30(5), ASPSPs must also make available a testing facility least six months before 14 September 2019 or at least six months before the target date of the market launch of the dedicated interface. As per the Final EBA Guidelines (Consultation Feedback Ref 119), ASPSPs should ensure that any changes are made available in the testing facility as soon as possible to allow TPPs to test against the updated technical specifications, in the context of compliance with Article 30(5). In practice, this means that ASPSPs should consider the impact of proposed changes on their testing facility in order to ensure that the testing facility enables the same functionality as the dedicated interface, in the context of such changes. As such, ASPSPs should endeavour to make any changes to the testing facility available to TPPs at least three months before changes are implemented to ensure TPPs, can continue to effectively test.
• ASPSPs should maintain multiple live/active versions of each interface (e.g. one for each supported release).
• Where an ASPSP choses to implement a new version of any component of the Standard they should implement each new major version within six months, and each new minor version within three months of the Standard being published by OBIE.

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:

• A long-lived consent (e.g. for access to AISP resources) created using an older version of the APIs can be used for read operations in newer versions of the API.
• A short-lived consent (e.g. for a short lived payment initiation request) can only be used within the same version of the API for creating resources.

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