BIAN Banking Architecture
How does BIAN classify APIs? Action Terms as the guideline
BIAN API classification works through Action Terms rather than a separate guideline document. Every Service Operation of a Service Domain executes exactly one Action Term, and these terms fall into four categories: SD Operations, Instantiation, Invocation and Reporting. Each operation is then exposed as a Semantic API Endpoint.
Is there an official API classification guideline in BIAN?
No, the book contains no document called an API classification guideline. What BIAN offers is a classification of Service Operations by Action Term, plus an approach for delimiting your own APIs. Both appear in the book BIAN 2nd Edition – A framework for the financial services industry, in sections 2.7 and 8.4.
It also helps to know what the classification leaves out. BIAN is strictly semantic, so non-functional requirements such as security, error handling and interaction style are deliberately not defined. Those choices stay with the bank. The Action Term list classifies what a service does, not how it is secured or implemented.
How does BIAN classify the services of a Service Domain?
BIAN characterizes every service with an Action Term, a fundamental unit of behavior that describes its purpose. The book puts it plainly: "Each Service Operation executes exactly one Action Term." The standard set is meant to cover all main types of service exchange a Service Domain might support.
The Action Term tells you the nature of an operation. What the operation actually achieves is clarified by the part of the Information Profile it refers to. The Current Account Service Domain illustrates this. 'initiateCurrentAccountArrangement' establishes a new current account facility, while 'executeCurrentAccountArrangementPayment' triggers a payment against an existing payment feature. The verb is the same kind of building block each time, and the subject changes.
What are the four categories of Action Terms?
Action Terms fall into four categories based on their effect: SD Operations, Instantiation, Invocation and Reporting. Table 25 in the book describes seventeen Action Terms in total: three for SD Operations, five for Instantiation, seven for Invocation and two for Reporting. The categories also apply to the Service Operations themselves.
| Category | Effect | Action Terms |
|---|---|---|
| SD Operations (3) | Influence the operation of the Service Domain overall as a service centre | activate, configure, feedback |
| Instantiation (5) | Create a new Control Record instance, starting a new life-cycle execution | create, initiate, register, evaluate, provide |
| Invocation (7) | Act on an existing Control Record instance, typically invoking a function or changing its state | update, control, exchange, capture, execute, request, grant |
| Reporting (2) | Obtain or subscribe to information, without changing the state of the instance | retrieve, notify |
The practical value is that the category already tells you something about risk and impact. A Reporting operation never changes state, while an Instantiation operation always starts something new.
How does a Service Operation become a Semantic API Endpoint?
Each Service Operation is made available through one Semantic API Endpoint, an access point to the environment. The collection of endpoints of one Service Domain forms its Semantic API. BIAN mapped this to the REST style, so the Action Term is converted into an HTTP verb and a noun.
REST exchanges the features and state of a resource, so the action is redefined as the outcome of that action. Table 26 in the book lists the full translation. A few examples:
| Action Term | Noun | HTTP verb |
|---|---|---|
| Initiate | Initiation | POST |
| Execute | Execution | PUT |
| Request | Requisition | PUT |
| Retrieve | maps directly to the HTTP GET method | GET |
Notify is not currently used in the BIAN mapping. BIAN also provides a Swagger File, generated from the Semantic API, for each Service Domain. Developers can use it as a starting point.
Keep expectations realistic, though. The endpoint descriptions only look like REST specifications to ease adoption, and the book stresses that they are some way from implementation-level specifications.
How do you delimit your own APIs with BIAN?
The book gives a stepwise approach: delimit service centres and services with wireframes, add Business Scenarios for context, elaborate API specifications, and detail and enrich the information exchange with the Business Object Model and message standards. Steps in brackets are only needed when BIAN does not supply a Semantic API.
- Delimit service centres and services, and prioritize (Open) APIs.
- Use wireframes to scope service centres and find enterprise boundaries.
- Use Business Scenarios to define the business context for Service Operations and their APIs.
- Elaborate the API specifications.
- (Transform Action Terms into HTTP verbs and nouns.)
- (Refine Service Operation functionality and API content based on the Information Profile and Control Record decomposition.)
- Detail the information exchange based on the Business Object Model.
- Enrich the information exchange based on Message Standards.
The Business Object Model matters because BIAN only provides generally applicable attributes. A bank's tailored BOM is a useful source of extra detail in a common language. For message standards such as IFX or ISO20022, the book notes that "BIAN is assigning a reference standard to Service Domains, i.e. a standard the Service Domain is maximally aligned to."
How granular should a bank's own APIs be?
Granularity is the bank's own choice, and the Semantic API Endpoints are a starting point, not a prescription. In the book's words: "A bank’s APIs do not need to be as ‘granular’ as the Semantic API Endpoints. What level of granularity the lowest ‘API nesting level‘ refers to, is a choice made by the bank’s architects."
The same freedom applies to non-functional requirements. Differences in interaction style or security may call for different API implementations, so the bank has to elaborate them itself. The wireframes and Business Scenarios from the approach above give the bank the context to do so. BIAN supplies the semantic layer, and the bank decides how to build on it.
Classification by behavior, not by implementation
BIAN classifies every Service Operation by exactly one Action Term, in one of four categories. Granularity, security and interaction style remain the bank's own decisions.
Ways to learn this standard
BIAN Foundation eLearning
Request a quote from a training partner
Frequently asked questions
BIAN deliberately leaves non-functional requirements such as security, error handling and interaction style to the bank. The framework is strictly semantic and implementation agnostic. These requirements depend on a bank's own circumstances and can call for different API implementations, so banks elaborate them themselves, using their wireframes and Business Scenarios as input.
Not necessarily, because the applicable Action Terms depend on the Functional Pattern of the Service Domain. The book shows in Figure 224 which Action Terms apply to which Functional Pattern. A Service Domain with a given pattern has Service Operations that correspond to those terms. Current Account, for example, has the fulfilment pattern.
Application and enterprise architects at banks and other financial institutions benefit most, especially when they delimit components and design application services and APIs. The classification gives them a shared business-level vocabulary for what each service does, before technology choices are made. It also helps developers who start from the Swagger File of a Service Domain.
Read BIAN 2nd Edition – A framework for the financial services industry by BIAN eV (ISBN 9789401807685). Section 2.7 covers Service Operations, Action Terms and the Semantic API. Section 8.4 covers the approach for future-proof APIs. Together they show how to move from classification to a bank's own API catalogue.
