Principles and Standards
The API's interface architecture is based on representational state transfer (REST). This decision is motivated by the aim for fast performance, reliability and the ability to scale, against the background of a state-of-the-art approach with a future-proofed perspective.
The API is documented by the use of up-to-date technologies to ease its use by software developers. Therefore, the complete documentation of the API specification is also available electronically, based on YAML OpenAPI 3.0.x files.
Where it is useful and possible with reasonable effort, existing standards will be used. If so, the standard used is declared accordingly in the code with the documentation function.
Full compatibility with all these standards is not sought for reasons of complexity.
ISO/TS 23029:2020 is a best-practice framework for developing APIs in financial services.
A summary of the basic considerations in ISO/TS 23029 which are relevant in the elaboration of specific Common API definitions can be found here.
To ease the design of the API Spec, an existing meta model for the definition of the business domains was wanted. The choice of the spec team fell on BIAN as conceptual foundation of the Common API Specification for Banking (CAPS).
Based on chapter 2.1 "NextGenPSD2 Access to Account Interoperability Framework - Implementation Guidelines V1.3.6".
The character set is UTF 8 encoded. This specification is only using the basic data elements "string", "boolean", "ISODateTime", "ISODate", "UUID" and "integer" and ISO based code lists (with a byte length of 32 bytes).
Max35Text, Max70Text, Max140Text resp. Max512Text are defining strings with a maximum length of 35, 70, 140 resp. 512 characters.
Banks and insurances will accept for strings at least the following character set:
a b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9
/ - ? : ( ) . , ' +
Space
Banks and insurances may accept further character sets for text fields like names, addresses, text. Corresponding information will be contained in the company's API documentation. Banks and insurances might convert certain special characters of these further character sets, before e.g. forwarding submitted data.
Common API response code approach is aligned to RFC9110 for success (2xx) and for client (4xx) and server errors (5xx). RFC7807 defines a way to carry machine-readable details of errors in a HTTP response (JSON Problem type). For more information see here.
Common API is using Semantic Versioning 2.0.0 and Path Versioning with major versions. For more information see here.
Common API supports offset- or cursor-based pagination. For more details see pagination Wiki page.
Consequently add example and default values for every request & response.
As far as possible and useful, example and default data should be included in the YAML file. So that we enhance the understandability.
Based on chapter 4.1 "NextGenPSD2 Access to Account Interoperability Framework - Implementation Guidelines V1.3.6".
The API definition follows the REST approach. This approach allows to transport message parameters at different levels:
- message parameters as part of the http level (http header)
- message parameters by defining the resource path (URL path information) with additional query parameters and
- message parameters as part of the http body. The content parameters in the corresponding http body will be encoded in JSON. The following principle is applied when defining the API. Message parameters as part of the http header:
- Definition of the content syntax
- Certificate and Signature Data where needed
- Customer identification data
- Protocol level data like Request Timestamps or Request/Transaction Identifiers
Message parameters as part of the path level:
- All data addressing a resource:
- provider identification,
- Service identification,
- Payment product identification,
- Account Information subtype identification,
- Resource ID,
- Additional information needed to process the request as process steering flags or filtering information,
Message parameters as part of the http body:
- Business data content
- Customer authentication data
- Messaging Information
- Hyperlinks to steer the full counterpart/client – bank process
The API is resource oriented. Resources can be addressed under the API endpoints https://{provider}/{service-endpoint}using additional content parameters {parameters} where
-
{provider}is the host of the API, which is not further mentioned -
{service}has values as consents, payments, bulk-payments, standing-orders, accounts, card-accounts or funds-confirmations, eventually extended by more information on product types and request scope -
{parameters}are content attributes encoded in JSON
URIs of service endpoints are made up by hyphenated pattern, e.g. /payments/sepa-credit-transfer.
The structure of the request/response is described in the following in the categories
- Path: Attributes encoded in the Path, e.g. “payments/sepa-credit-transfers” for {resource}
- Query Parameters: Attributes added to the path after the ? sign as process steering flags or filtering attributes for GET access methods
- Header: Attributes encoded in the http header of request or response
- Request: Attributes within the content parameter set of the request
- Response: Attributes within the content parameter set of the response, defined in JSON
In accordance with TBG (The Berlin Group) conventions. The following naming conventions are used for body parameters:
- spinal-case (small letters) on path level
- Spinal-case (starting capital letters) on HTTP header level and
- lowerCamelCase for query parameters and JSON based content parameters.
This also includes acronyms: No uppercase for standard acronyms, even if it may be less readable (e.g. the abbreviation for the International Bank Account Number, which is named iban here).