Central Design Decisions
The specification of the Card API is structured in different maturity levels, i.e. from an API modelling point of view, a Matryoshka approach is chosen here. This ensures that different users of the API with different availabilities of information 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. Parties negotiate among themselves which level of the API should be used; ideally, level 3, the most comprehensive level of the API, is aimed for, as this ensures maximum compatibility.
The levels build on each other. This means that level 1 supports the least functionality, but also requires the least information for use. Level 3 offers broader functionality with additional endpoints, but must also be used with complete data on the person/card/account. As the levels build on each other, it is also possible to communicate to lower levels via a proxy that filters the corresponding fields. For example, a data provider can have implemented level 3, but the proxy or end user can only map level 1 information and still receive corresponding responses for level 1.
Please note that the three-tiered approach does not reflect the three 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