The appearance of the open banking concept, especially with the enforcement of Payment Services Directive 2 (PSD2) in the EU, is changing the landscape of the banking sector. The directive, now being replicated worldwide, pushes to end banks’ monopoly on their customers’ financial data, obliging banks to make it shareable with regulated Third Party Providers (TPP). This sharing is done through the bank’s Advanced Programming Interface (API) with the appropriate wishes and consents of the TPP customer. 

While the technology of API has existed for over 30 years now, it is somewhat a novelty to most banks as it has been viewed with caution because of security issues. Therefore, there is no unified standard yet, but Regulatory Technical Standards (RTS) and PSD2 help to shape the main API and its documentation frameworks across Europe – UK Open Banking, the Berlin Group, and STET.

What do APIs do?

API is a way for businesses to enable third parties to request, share and modify data and services within their system from outside. Institution chooses what kind of data is accessible and adaptable, creating documentation for the API to explain to third parties how to use it. If you encounter problems in API integration, you can always contact a Los Angeles software development company that can help you with your integration.

APIs are usually created adhering to the Representational State Transfer (REST) architectural constraints. When a client requests via REST API, it transfers the state of information to the requester or some endpoint. It is typically, but not necessarily, delivered through HTTP(S) protocol via JSON format. 

In open banking, the Account Information Service Provider (AISP) requests needed data from the bank’s API to provide a specific service. Similarly, the Payment Initiation Service Provider (PISP) requests the API to initiate payment into or out of the customer’s account.

Open banking API design patterns

API design patterns dictate how the APIs operate and what is essential to be noted in its documentation. European Standards are currently the most advanced for most common API design patterns: Design By Role, Positive Acknowledgement, and Assertion of Truth. Each pattern appears due to either a regulatory or architectural requirement or prevalent themes in financial services.

Design by Role

Due to the need to regulate providers that access and interact with sensitive data, PSD2 defined two new roles in the payment market – AISPs and PISPs. Different providers have specific permissions of what they can and cannot access, resulting in a Design by Role pattern. It means there must be different APIs or endpoints that a particular provider can interact with within their legal authorization.

Positive Acknowledgement

While REST APIs usually follow the minimalistic approach, trying to limit bandwidth and provide just enough data to a client, interpreting they know the state of resources already, open banking APIs tend to choose a different perspective. Its aim is to ensure the client’s awareness of the resource and information state so there would be no room for unnecessary interpretation. Such a pattern is called Positive Acknowledgement.

Assertion of Truth

Additionally, there is an Assertion of Truth pattern. An API design that offers cryptographic proofing through a message signing of an API call or request. Such an approach is implemented in the majority of financial and payment systems around the world. There is undisputed evidence of an API call or request that an API consumer or its administrator can provide. In open banking, this is a direct way to understand who issued the payment, who owes who, and assigning responsibility to a faulty party if needed.

Recommendations for API documentation 

Other than open banking design patterns to consider, there are also general recommendations for creating API documentation. These practices are usually followed to make API easy to use and save time and costs on support tickets. In the beginning, it is important to draft a plan for the documentation. Questions like the target audience and the intentions for using the API have to be answered before starting the actual preparation of the documentation. 

API documentation is supposed to entail five of the fundamental sections:

1. Overview section, which provides and introduces vital information for the user onboarding process. 

    2. Description of the authentication process and access to its credentials and how the keys for making requests operate are necessary, especially for an open banking API. 

    3. The resources section must be thoroughly covered, as it is the core component of API documentation. TPPs will interact with API’s resources, so it is essential to provide all the information about endpoints, parameters, and other details. 

    4. There should also be clear and helpful error messages, which would explain the reason for failed operations or actions. 

    5. In addition, terms of use outline the legal agreement on the use of the bank’s API services.

API documentation should be consistent and avoid jargon to make it easy to read and eliminate ambiguity. It is also important to have interactive examples for consumers and businesses to visualize how the API and code written for it might operate. API documentation is always a work in progress, so it should be constantly maintained and reviewed, as the API functionality will change over time.