3. API Style Guide (Draft Version 1.0)
The API design MUST follow a style guide to ensure that it remains consistent in its overall implementation during incremental version updates.
3.1 Resource URI Path Structure and Syntax
The REST architecture leverages a stateless communication protocol (e.g., HTTPS), whereby resources are accessed using uniform resource identifiers (URIs) which are typically links on the web. A consistent URI structure with short and meaningful descriptors could be used for Open Banking API endpoints to facilitate integration. The path of the URI must follow the structure below:
[participant-path-prefix]/open-banking/[version]/[resource-group]/[resource]/[resource-id]/[sub-resource]
This consists of the following elements:
[participant-path-prefix]
An optional ASPSP specific path prefix.
open-banking
The constant string "open-banking".
[version]
The version of the APIs expressed as /v[major-version].[minor-version]/.
[resource-group]
The resource-group identifies the group of endpoints
[resource]/[resource-id]
Details the resource.
[sub-resource]
Details the sub-resource.
An ASPSP must use the same participant-path-prefix and host name for all its resources.
Sample HTTP Headers and URI path structures are provided below:
HTTP Header:
POST /account-access-consents HTTP/1.1
GET /beneficiaries HTTP/1.1
URI Path Structure:
https://abcbank.com/apis/open-banking/v3.0.0/aisp/OBAccountAccessConsentRequest
https://abcbank.com/apis/open-banking/v3.0.0/aisp/OBReadBalance
3.2 Links
ASPSP may return all API resource relationships via a Links JSON object. This object SHOULD provide the OBSP with the absolute URIs required to thereafter fetch those related API resources for the Customer.
A candidate for a Links JSON object is paginated API responses, whereby Links will indicate e.g., current page, first page last page, next page, previous page.
3.3 Meta
The Meta section is optional and may be empty. An optional member is “TotalPages” which is specified as an integer (int32) and shows how many pages of results (for pagination) are available.
For example:
"Meta": {
"TotalPages": 13
} 3.4 Filtering
An ASPSP must provide limited support of filtering on GET operations that return multiple records.
The filter parameters are always specific to particular field(s) of the resource and follow the rules/formats defined under the resource’s data dictionary.
In case of DateTime type filter parameters, values must be specified in ISO8601 format. If the DateTime contains a time zone, the ASPSP must ignore the time zone component.
The filter values will be assumed to refer to the same time zone as the time zone in which the resource is maintained.
3.5 Pagination
An ASPSP MAY provide a paginated response for GET operations that return multiple records.
In such a situation, the ASPSP MUST:
If a subsequent page of resource records exists, the ASPSP must provide a link to the next page of resources in the Links.Next field of the response. The lack of a next link would suggest that the current page is the last page of results
If a previous page of resource records exists, the ASPSP must provide a link to the previous page of resources in the Links.Prev field of the response. The lack of a previous link would suggest that the current page is the first page of results
For a paginated response, the ASPSP SHOULD ensure that the number of records on a page are within reasonable limits.
Additionally, the ASPSP MAY provide:
A link to the first page of results in the Links.First field
A link to the last page of results in the Links.Last field
The total number of pages in the Meta.TotalPages field
As with all other responses, the ASPSP MUST include a “self” link to the resource in the Links.Self field as described in the Links sections.
This standard does not mention how the pagination parameters are passed by the ASPSP and each ASPSP may use their own mechanisms to paginate the response.
If the original request from the AISP included filter parameters, the paginated response must return only results that match the filter.
ASPSPs are not expected to implement pagination with transaction isolation. The underlying dataset may change between two subsequent requests. This may result in situations where the same transaction is returned on more than one page.
3.6 Key Stores
A Trust Anchor that is trusted by the ASPSPs and OBSPs is responsible for providing a store of public keys for each of the parties
The Trust Anchor must provide a means for any of the parties to retrieve public keys to verify messages
As part of Kuwait Open Banking PACI and other entities as applicable and licensed by PACI can issue the public keys for ASPSPs and OBSPs
3.7 Specification
The OBSP must sign the HTTP body of each API request that requires message signing
The ASPSP must sign the HTTP body of each API response that requires message signing
The ASPSP should verify the signature of API requests that it receives before carrying out the request. If the signature fails validation, the ASPSP must respond with a 400 (Bad Request)
The ASPSP must reject any API requests that should be signed but do not contain a signature in the HTTP header with a 400 (Bad Request) error
The OBSP should verify the signature of API responses that it receives
The signer must sign the message with PS256
3.8 API Allowed Types
Private APIs: Private APIs are only accessible by authorized users and may be subject to usage restrictions. These APIs are made available to limited trusted external parties
Partner APIs: Partner APIs are available to authorized partners of the API provider and may have special terms and conditions associated with their use
Public APIs: Public APIs are open to the general public and external developers. Public APIs are typically governed by a Terms of Use or license agreement between the developer and the API provider
3.9 Supplementary Data
A number of resources in the specification include a section for Supplementary Data. This is intended to allow ASPSPs to accept or provide information in a request or response that is not catered for by other sections of the resource definition
The Supplementary Data section is defined as an empty JSON object in the specification
Wherever used, an ASPSP must define and document their own structure, usage and (mandatory/optional) requirements for Supplementary Data
An ASPSP must not use Supplementary Data if an element already exists in the standard that fulfils the requirement
3.10 Archiving
Archiving of resources will be for ASPSPs to define based on their internal Legal and Regulatory requirements.
In addition:
ASPSPs must only patch expired intent-ids 24 hours after creation
ASPSPs may archive these expired intent-ids
Participants may look to adhere to the national, international best practices and legal requirements for archiving:
Participants to comply with the data retention policies with respect to the instructions defined by the Central Bank of Kuwait (10 years)
Participants to implement robust security measures to protect archived resources such as encryption and access control to prevent any unauthorized access/tampering
Participants to adhere to international standards such as ISO 27001 for ensuring a systematic approach to manage sensitive data
Participants to comply with the local data protection instructions for processing and storage of data
3.11 JSON
JSON Web Tokens (JWTs)
The JSON Web Token Standard (JWT) MUST be used as the Token Format for all API resource requests between the OBSPs and ASPSP when sharing claims data.
JSON Web Encryption (JWE)
Message Encryption within the JWT MUST be implemented through the JSON Web Encryption Standard (JWE) to assist with non-repudiation
JSON Web Signatures (JWS)
Message Signing within the JWT MUST be implemented through the JSON Web Signature Standard (JWS) to assist with non-repudiation
3.12 Date Formats
All dates in JSON payloads are represented in ISO-8601 date-time format
3.13 Character Encoding
MUST use UTF-8 character encoding for the application/json Content-Type
MUST use Base64 encoding for any signed (application/jwt) or binary (application/pdf) Content-Type
3.14 Versioning
Establishing a well-defined version control in the development of the Kuwait Open Banking Technical API specifications helps to ease maintenance, change-management, bug-tracking and backward compatibility. The banks could adopt the following practice to manage the versioning of the Open Banking API specifications: v[major-version].[minor-version].[bug-fix]:
Major: Version update only when major changes are applied across all or most of the Open Banking API specifications
Minor: Version update only when major changes are applied at the Open Banking API specifications endpoints level
Bug fix: Version update only when minor documentation changes are made to clarify or rectify the Open Banking API specifications
3.15 API Fair Usage Policy
An API fair usage policy enables the Bank to adjust its API performance through configuration by controlling the throughput of incoming requests. The Bank could consider limiting the number of requests to Open Banking APIs to ensure optimal performance through the configuration of two parameters:
Request Rate Limit: Represents the maximum number of requests that the API can handle in a stable, consistent, and successful manner in a set period
Thrust Limit: Represents the maximum number of requests simultaneously served (in 1 millisecond) by the API
When requests exceed the rate limit or thrust limit, the Bank could stop processing the request and return “HTTP Response Code: 429 – Too Many Requests” error response to the OBSP. The OBSP could resubmit the request while complying with the usage policy. The Bank could set access control configuration at the OBSP level based on its API fair usage policy agreed with the OBSP through a bilateral agreement.