Page Comparison

Restful APIs

The API adheres to RESTful API concepts where possible and sensible to do so.

However, the priority is to have an API that is simple to understand and easy to use. In instances where following RESTful principles would be convoluted and complex, the principles have not been followed.

References:

• The highest level Data Description Language used is the JSON Schema : http://json-schema.org/

• Best Practice has also been taken from the Data Description Language for APIs; JSON API : http://jsonapi.org/

• The Interface Description Language used is the Swagger Specification version 3.0.0 (also known as Open API) : http://swagger.io/

ISO 20022

In keeping with that requirement, the API payloads are designed using the ISO 20022 message elements and components where available.

The principles we have applied to re-use of ISO message elements and components are:

• Only elements that are required for the functioning of the API endpoint will be included in the API payload. API endpoints are defined for specific use-cases (not to be generically extensible for all use-cases).

• We will modify ISO 20022 elements where the existing standard does not cater for an API context (such as filtering, pagination etc.).

An idempotency key is used to guard against the creation of duplicate resources when using the POST API endpoints (where indicated).

If an idempotency key is required for an API endpoint:

• The x-idempotency-key provided in the header must be at most 40 characters in size. If a larger x-idempotency-key length is provided, the ASPSP must reject the request with a status code is 400 (Bad Request).

• The AISP/PISP must not change the request body while using the same x-idempotency-key. If the AISP/PISP changes the request body, the ASPSP must not modify the end resource. The ASPSP may treat this as a fraudulent action.

• The ASPSP must treat a request as idempotent if it had received the first request with the same x-idempotency-key from the same AISP/PISP in the preceding 24 hours.

• The ASPSP must not create a new resource for a POST request if it is determined to be an idempotent request.

• The ASPSP must respond to the request with the current status of the resource (or a status which is at least as current as what is available on existing online channels) and a HTTP status code of 201 (Created).

• The ASPSP may use the message signature, along with the x-idempotency-key to ensure that the request body has not changed.

If an idempotency key is not required for an API endpoint:

• The ASPSP must ignore the idempotency key if provided.

The APIs require TLS 1.2 Mutual Authentication and this may be used as a means of non-repudiation. However, it would be difficult to maintain digital records and evidence of non-repudiation if the API only relied on TLS 1.2.

A solution for non-repudiation that does not rely on TLS, would be achieved by providing a JWS with detached content (as defined in RFC 7515 - Appendix F) in the HTTP header of each API request.

The HTTP body would form an un-encoded payload as defined in RFC 7797.

The JWS would be signed using an algorithm that supports asymmetric keys.

A request would be signed by a AISP/PISP's private key and a response would be signed by the ASPSP's private key.

Not all API requests and responses are signed. Whether message signing is mandatory, supported or not supported is documented along with each API.

Message encryption is implemented through JSON Web Encryption (JWE).

The approach differs from message signing in that:

• The entire request or response payload is delivered in the form of an encrypted JWT.

• The definition of a given request or response in the Swagger specification represents the decrypted payload.

• The JWE will not be represented in its encrypted form in the Swagger specifications.

• Sending or expecting to receive an encrypted payload is denoted by setting the Accept or Content-type header to application/jose+jwe.

If an ASPSP does not support message encryption then should reject any requests with a Content-type or Accept headers that indicate that message encryption is required.

A REST resource should have a unique identifier (e.g. a primary key) that may be used to identify the resource. These unique identifiers are used to construct URLs to identify and address specific resources.

However, considering that some of the resources described in these specifications do not have a primary key in the system of record, the Id field will be optional for some resources.

An ASPSP that chooses to populate optional Id fields must ensure that the values are unique and immutable.

The functionality, endpoints and fields within each resource are categorised as 'Mandatory', 'Conditional' or 'Optional'.

Mandatory

Functionality, endpoints and fields marked as Mandatory are required in all cases for regulatory compliance and/or for the API to function and deliver essential customer outcomes.

For functionalities and endpoints:

• An ASPSP must implement an endpoint that is marked Mandatory.

• An ASPSP must implement functionality that is marked Mandatory.

For fields:

• A AISP/PISP must specify the value of a Mandatory field.

• An ASPSP must process a Mandatory field when provided by the AISP/PISP in an API request.

• An ASPSP must include meaningful values for Mandatory fields in an API response.

Conditional

Functionality, endpoints and fields marked as Conditional may be required in some cases for regulatory compliance (for example, if these are made available to the USER/CUSTOMER in the ASPSP's existing Online Channel, or if ASPSPs (or a subset of ASPSPs) have been mandated by a regulatory requirement).

For functionalities and endpoints:

• An ASPSP must implement functionality and endpoints marked as Conditional if these are required for regulatory compliance.

For fields:

• All fields that are not marked as Mandatory are Conditional.

• A AISP/PISP may specify the value of a Conditional field.

• An ASPSP must process a Conditional field when provided by the AISP/PISP in an API request, and must respond with an error if it cannot support a particular value of a Conditional field.

An ASPSP must include meaningful values for Conditional fields in an API response if these are required for regulatory compliance.

Optional

Functionality and endpoints marked as Optional are not necessarily required for regulatory compliance but may be implemented to enable desired customer outcomes.

For functionalities and endpoints:

• An ASPSP may implement an Optional endpoint.

• An ASPSP may implement Optional functionality.

For fields:

• There are no Optional fields.

For any endpoints which are implemented by an ASPSP, the fields are either Mandatory or Conditional.

The API requests and responses must use a UTF-8 character encoding. This is the default character encoding for JSON (RFC 7158 - https://tools.ietf.org/html/rfc7158#section-8.1)

However, an ASPSP's downstream system may not accept some UTF-8 characters, such as emoji characters (e.g. "J" may not be an acceptable Payment Reference). If the ASPSP rejects the message with a UTF-8 character that cannot be processed, the ASPSP must respond with an HTTP 400 (Bad Request) status code.

All date-time fields in responses must include the timezone. For Example:

The API allows the AISP to ask an ASPSP to create a new account-access-consent resource.

All dates in the query string are represented in ISO-8601 date-time format and must not include the timezone. For example:

All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below:

All dates in the JWT claims are expressed as a JSON number, representing the number of seconds from 1970-01-01T0:0:0Z as measured in GMT until the date/time.