Best Practices ISO 23029

Owned by Rolf Wagner
Last updated: Mar 24, 2023

ISO/TS 23029:2020 is a best-practice framework for developing APIs in financial services.

https://www.iso.org/standard/74353.html

The following is a summary of the basic considerations in ISO/TS 23029 which are relevant in the elaboration of specific Common API definitions. Therefore, ISO 23029 considerations that are not relevant to Common API due to

  • (design) decisions already made (e.g., OpenAPI, HTTPS, REST, FAPI API Security, etc.)

  • their applicability for specific implementation work

will not be listed or discussed here.

Remark: Quotations from the ISO standard are marked like this.

Design Principles

For Common API relevant ISO 23029 design principles.

Extensibility

Where possible, design decisions for the API ecosystem should be designed to be as extensible as possible. Data standards may change, but the API does not. This is to ensure that their use is able to adapt to future use cases or scenarios.

Non-repudiation

Non-repudiation is important for the validity of data of exchange in Web APIs and will enforce the confidence in the data to be exchanged. Digital signatures could be used in the context of an API.

Web resource unique identifiers (ID fields)

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

Idempotency

Idempotency shall be considered upfront for a Web API.

Resource Path

The resource path is a chain of one or more resource hops with the following components:

/[Resource Type]/[Resource ID] → e.g. /payments/23564323

The standard pattern is to use names for resources that are in the plural form to designate the collection of resources of the same type (e.g. ‘orders’, not ‘order’). The most widely used character case convention for resource types is spinal-case. Words are in lower case and separated with hyphens.

The last resource hop in the resource path is the effective target of the API request. If this hop has, this means the target is actually the single resource which matches with the ID. If not, the target is the collection of all accessible resource IDs.

Common API examples:

  • /accounts → Returns the list of all accounts accessible for the logged in user.

  • /accounts/{accountID} → Returns a specific account.

  • /accounts/{accountID}/transactions → Transactions to and from the specified account.

This structure should be applied to the endpoints as far as possible, if no stringent (business) usage requirements speak against it.

When multiple resource hops are specified within a resource path, it is assumed that each resource, except the first one, is semantically linked to the previous one in the path.