Central Design Decisions
The specification of the Card API is structured in different maturity levels. From an API modelling point of view, a Matryoshka approach is chosen to ensure that different API users with different levels of information availability can still follow as similar an approach as possible. It also enables a more precise definition of the data model for data providers who do not want to offer all entities.
The two levels build on each other. This means that level 1 supports the basic functionality and requires less information for use. Level 2 offers broader functionality with additional endpoints, but also requires more complete data on the person/card/account. As the levels build on each other, it is possible to communicate to lower levels via a proxy that filters the corresponding fields. For example, a data provider can have implemented level 2, while the proxy or end user can only map level 1 information and still receive corresponding level 1 responses.
Parties negotiate among themselves which level of the API should be used; ideally, level 2, the more comprehensive level of the API, is aimed for, as this ensures maximum compatibility.
Please note that the two-tiered approach does not reflect card types, but different use cases as described below.
The parameter names allow an easy recognition of the type of underlying identifier. The three following words are used as part of the parameter names for distinction:
- *Id: technical identifier for an instance of a resource which is always in the UUID format. It is used for direct access to a resource instance in an API endpoint. The UUIDs follow a standardized pattern, are assigned by the data provider and are not guaranteed to be unique across data providers. The method by which a user obtains access to the id can vary depending on the provider (e.g., as part of the consent flow).
- *Reference: functional identifier for an instance of a resource that can also be known by an end cus-tomer, is a generic string without a standardized format
- *Code: identifier for an instance of a resource, can be mapped to a name in a finite set of values, is a generic string without a standardized format
The attributes in the ca-card standard which are defined with a general String datatype, support at least the characters defined in the global SFTI Common API standard. Please refer to the definition in the Common API wiki: https://github.com/swissfintechinnovations/.github/wiki/Character-Set
API Providers are however free to use additional characters. API Consumers are advised to use a flexible implementation for handling the additional characters.