Last updated: 20 February 2021

This week saw the release of OpenAPI Specification version 3.1.

The OpenAPI Specification is a standard that allows API providers to describe what an API does in a way that is easily understood by developers, but is also in machine readable format, so that it can be integrated into software development and API lifecycle and other tools.

For example, a bank could prepare an OpenAPI Specification for a Payments API.

Internally, the bank's API team can put the OAS into their API lifecycle tooling so that at testing and design stages, they can check whether the API being designed matches the original intention as described in the OAS.

When the API is made available externally, a fintech developer can then open the OpenAPI Specification file, and because it is laid out in a consistent, standardised manner, they can quickly understand the main functionalities (and any restrictions) of the API. They can also integrate the OpenAPI Specification file into their software tooling so that API endpoints (or resources) are more easily visible in their tooling, and their software development environment can alert them if they attempt to use the API in a way that is out of scope.

Using open standards in open banking ecosystems

Building APIs in open banking to industry agreed open standards is a key enabler for open ecosystem growth. Open standards, like using the OpenAPI Specification standard, can assist banks and fintech API platforms  to unlock the value in their API portfolio faster:

• More consistent internal design with less errors and challenges in the API design process, as the OAS can be used in API lifecycle tools to ensure that the API maintains alignment and is tested against the API intent, as described in the OAS
• Less costs on documentation and support queries as more developers understand how the API functions
• Faster time to market for API consumers building revenue-generating products as they are able to understand and incorporate the API into their software development toolchain
• More robust security as restrictions and specific requirements can be defined within the API definition. Because the API definition is built to a common standard, it has already been tested by a community of users for potential vulnerabilities, whereas a bespoke, individual approach to describing an API in a machine readable way will only have had a smaller number of security reviews done.

The API Specification Toolbox includes resources on all types of API specification standards and other API-related standards, including tools and resources for the OpenAPI Specification.

Increasing adoption of the OpenAPI Specification in open banking

In the banking sector, the OpenAPI Specification is gaining traction worldwide. We have identified that, globally, 75% of all open banking platforms design their APIs by using an OpenAPI Specification to describe the API. In Q4 2020, use of OAS grew by 68% over adoption levels in Q3 2020. The growth was mostly driven by the following factors:

• Intermediary bodies and marketplace platforms, like LUXHUB, that manage PSD2 APIs on behalf of some European banks, generally make sure that all banks on their platform make their APIs available with an OAS file.
• Some banks like to build their APIs with an OAS file as they can then make use of auto-generated documentation tools that can be instantly spun up as the API reference for a banking API. In some instances, we are seeing that where banks are not yet investing in developer on-boarding or developer resources to encourage API integration and use, by using an OAS file they can spin up an API reference guide automatically.

Automatic documentation with OAS: An example

Some banks are creating APIs because they are required to do so by regulations. For example, in Europe, UK, Brazil, Australia, and other regions where we track open banking regulations, banks of a certain size are required to have APIs available for specific functionality (usually payments initiation, and account information, but also bank products and ATM locations in some regions.)

In some cases, banks may just be complying with regulations because they haven't got a solid platform play in mind for ensuring their banking APIs are adopted and grow out in an ecosystem approach. Some banks are still thinking through what a platform approach means, and in the meantime have to put their APIs up, or are testing the waters on levels of interest, but don't want to invest heavily in developer experience, which we see as a key enabler in helping platforms to grow.

An OAS file can help these banks to comply quickly and also start to see interest in their emerging API products. Societe-Generale in France, for example, appears to be moving towards a platform approach: they have a basic API developer portal, but rather than just do a very basic regulation-compliant payments API, they have gone to a granular level of functionality, and have also created an API for product locations, which is not required by regulation in France.

So while they have a very basic developer portal at present, they appear to have an ecosystem approach in mind for the future, as they are investing in building APIs that are suited to specific purposes, rather than a single regulation-compliant API that is not expected to be used. While they figure that out though, by using OAS, they have been able to autopopulate their API documentation.

(This is platform approach is further backed up by Isabel Woodford's interview with Societe-Generale's CIO, Claire Calmejane. Calmejane describes a model that matches the third type of our fintech financing/business model categorisation: incubators and acquisitions.)

As shown in the following screenshots, they have a documentation page for each API (on the left). The API documentation includes an interactive accordion-style menu option where you can click and expand more information about each API functionality. The second screenshot below shows this with the payments request functionality. On the right, you can see the OAS file in a text editor. Here, you can see that the Societe-Generale API team has written the OAS file in a way where it is used to autopopulate the documentation in the middle and on the left.

Regional differences in OAS adoption in open banking

It is possible to count the number of banks that are using a version of OpenAPI Specification (419 out of 559), but we find it more useful to look at the percentage of all banks in each region that use OpenAPI. This can give an insight into the scalability and developer friendliness of banking APIs in each region overall.

For example, Europe and the UK is seeing the greatest adoption of OAS as a description standard for banking APIs, with over 75% of open banking platforms building to OpenAPI Specification standards.  

Regions with countries that have more recently passed or started consultation processes on open banking regulations - Latin America and the United States - are seeing less uptake of OAS as a standard at this stage (with both hovering at just over 25% of all current banking platforms using OAS).

We believe it is important for the OpenAPI Initiative to seek out partners and relationships with banking and finance stakeholders now, at the nascent stage of open banking in those regions. This would encourage more widespread industry use of OAS so that banks start building with OAS as a standard from the start.

With new regulations in Brazil, Mexico, and consultations on financial data and integrated services just finishing in the United States, open banking regulatory activity in these geographic markets is expected to intensify in 2021.

Banks

What this means for banks and fintech platforms

OAS provides a mechanism for banks and fintech that are designing APIs to build to current industry standards. Use of OAS helps internal teams to build robust APIs that meet their business purpose, and also helps API consumers understand the functionality of an API in a consistent format. Banks with revenue or adoption targets for their APIs can progress faster by using OAS, as it makes it easier for external developers to build with APIs.

Fintech Associations

What this means for fintech associations

Fintech associations can educate and support their members to understand the OpenAPI Specification standard and encourage members to seek out banking APIs that offer an OAS file with their APIs, as this is an indicator that a bank’s APIs have a better fitness-for-purpose, will be able to support scalability when the fintech extends into new markets, and are more robust in their design, with less potential security flaws.

Regulators

What this means for regulators

We encourage regulators to mandate the use of open standards in open banking regulations. For example, regulations could insist that banks use a specification standard when describing their APIs. This would make their country’s open banking ecosystem more secure, and would support API consumers to build faster, reaching viability as new businesses faster, extending the potential range of consumer financial services products available in the market, and possibly even increasing the range of financially inclusive product offerings as part of this widening choice.

Banking regulators or regulator bodies that mandate that banks must build their APIs to template standards can create OpenAPI Spec files for their API standards. For example, the UK Open Banking Standard publishes an OAS file. That means that banks using the required API standard when designing their API can do so quickly and in line with standardisation requirements by starting with the OAS file.

Further reading:

• OpenAPI Specification version 3.1 release notes
• Lorna Jane Mitchell presented on the new version features of OpenAPI Specification 3.1 at the apidays Paris event in December 2020.
• API Evangelist: Intro to OpenAPI Office Hours