BIAN Banking Architecture
Welke richtlijn geldt voor API-classificatie in de BIAN-architectuur?
BIAN kent geen apart document met de naam API classification guideline. De API-classificatie in de BIAN-architectuur loopt via Action Terms: elke Service Operation voert precies één Action Term uit, en die termen vallen in vier categorieën. Elke operation wordt ontsloten via een Semantic API Endpoint.
Wat is API-classificatie in de BIAN-architectuur?
BIAN classificeert de services van een Service Domain niet met een losse richtlijn, maar met Action Terms. Elke Service Operation heeft precies één Action Term, die het doel van de service vastlegt. Die operation wordt via een Semantic API Endpoint beschikbaar gesteld; alle endpoints samen vormen de Semantic API van het domein.
Een Action Term is volgens BIAN Banking Architecture een fundamentele eenheid van gedrag. In paragraaf 2.7.1 van BIAN 2nd Edition – A framework for the financial services industry staat de kernregel kort samengevat: "Each Service Operation executes exactly one Action Term." De verzameling termen is bedoeld om alle hoofdtypen van service-uitwisseling te dekken die een Service Domain kan ondersteunen.
Welke operations een domein heeft, hangt af van zijn Functional Pattern. Een Service Domain met een bepaald patroon biedt Service Operations die bij die Action Terms horen. De classificatie is dus geen aparte laag bovenop de architectuur, maar zit in de manier waarop BIAN een service definieert.
Welke vier categorieën Action Terms onderscheidt BIAN?
BIAN groepeert de Action Terms naar hun effect in vier categorieën: SD Operations, Instantiation, Invocation en Reporting. Tabel 25 in het boek beschrijft zeventien Action Terms: drie voor SD Operations, vijf voor Instantiation, zeven voor Invocation en twee voor Reporting. Die indeling geldt ook voor de bijbehorende Service Operations.
Het boek zegt het zo: "The BIAN Action Terms can be grouped in four main categories, related to their effect." Het effect bepaalt dus in welke groep een operation valt.
| Categorie | Action Terms | Effect |
|---|---|---|
| SD Operations | activate, configure, feedback | Werkt op de werking van het Service Domain als geheel, als service centre. |
| Instantiation | create, initiate, register, evaluate, provide | Leidt tot een nieuwe Control Record-instantie, dus een nieuwe levenscyclus. |
| Invocation | update, control, exchange, capture, execute, request, grant | Werkt op een bestaande Control Record-instantie, meestal door een functie aan te roepen of de status te wijzigen. |
| Reporting | retrieve, notify | Haalt informatie op of abonneert erop, zonder de status van de instantie te veranderen. |
Een voorbeeld uit het Current Account Service Domain maakt het concreet. Met initiate ontstaat een nieuwe rekeningfaciliteit; met execute wordt een betaling getriggerd op een bestaande betaalfunctie.
Hoe wordt een Service Operation een Semantic API Endpoint?
Elke Service Operation wordt via een Semantic API Endpoint naar buiten ontsloten, als toegangspunt van één operation van één Service Domain. De verzameling endpoints van een domein vormt de Semantic API. Het is een hoog-niveau specificatie van het zakelijk doel en de informatie-inhoud, nadrukkelijk geen implementatiespecificatie.
BIAN is bewust implementatie-agnostisch, maar heeft de definities wel gekoppeld aan de REST-architectuurstijl. De Action Term wordt daarbij omgezet in een http-methode en een zelfstandig naamwoord. De actie wordt dan het resultaat van die actie, en dat past beter bij hoe REST resources behandelt. Tabel 26 in het boek geeft de vertaling. Enkele voorbeelden:
- Initiate wordt Initiation met POST.
- Execute wordt Execution met PUT.
- Retrieve komt direct overeen met GET.
- Notify wordt in de BIAN-mapping momenteel niet gebruikt.
Uit de Semantic API wordt per Service Domain een machineleesbaar Swagger File gegenereerd, dat als startpunt voor een implementatie dient. Het boek waarschuwt wel dat de endpoint-beschrijvingen er alleen uitzien als REST om ontwikkelaars te helpen. Ze liggen nog een flink stuk van een implementatiespecificatie af.
Welke stappen volgt een bank om eigen API's af te bakenen?
Het boek beschrijft een stappenaanpak die begint bij het afbakenen van service centres en services en eindigt bij het verrijken van de informatie-uitwisseling met berichtstandaarden. Stappen tussen haakjes zijn niet nodig als er BIAN-Semantic APIs beschikbaar zijn. Daartussen gebruik je wireframes, Business Scenarios en het BOM.
- Bakenen service centres en services af en geef (open) API's prioriteit.
- Gebruik wireframes om service centres af te bakenen en de grenzen van de onderneming te vinden.
- Gebruik Business Scenarios als zakelijke context voor Service Operations en hun API's.
- Werk de API-specificaties uit.
- (Zet Action Terms om in http-verbs en zelfstandige naamwoorden.)
- (Verfijn de functionaliteit van de Service Operation en de API-inhoud op basis van het Information Profile en de decompositie van het Control Record.)
- Detailleer de informatie-uitwisseling met het Business Object Model.
- Verrijk de informatie-uitwisseling met berichtstandaarden.
Een wireframe werkt als een plattegrond van een stad: hij toont de mogelijke paden tussen Service Domains. Een Business Scenario is één route over die plattegrond. Het boek wijst erop dat gestandaardiseerde en goed beveiligde API's het belangrijkst zijn waar verschillende partijen met elkaar communiceren, zoals de bank, de klant en een externe dienstverlener.
Hoe gedetailleerd moeten de API's van een bank zijn?
Dat bepaalt de bank zelf: de API's hoeven niet zo granulair te zijn als de Semantic API Endpoints. Het boek laat de keuze voor het laagste API-nestingniveau uitdrukkelijk bij de architecten van de bank. Ook non-functionele eisen als beveiliging en interactiestijl laat BIAN bewust aan de bank.
In paragraaf 8.4.2 staat het zo: "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." Verschillen in non-functionele eisen kunnen om verschillende API-implementaties vragen. Wireframes en Business Scenarios helpen de bank om die eisen uit te werken.
De informatie-inhoud moet de bank altijd zelf verder invullen, omdat BIAN alleen algemeen toepasbare attributen levert. Het Business Object Model, of een op de bank toegesneden variant, is daarvoor een nuttige bron. Berichtstandaarden zoals IFX of ISO20022 kunnen de inhoud ook verrijken. Daarbij geldt: "BIAN is assigning a reference standard to Service Domains, i.e. a standard the Service Domain is maximally aligned to."
Wanneer gebruik je de Action Term-classificatie?
Gebruik de Action Term-classificatie wanneer je application services en API's wilt afbakenen op semantisch zakelijk niveau, bijvoorbeeld bij een architectuur met losse koppeling of microservices. Groepen Service Operations bakenen de functionaliteit van application services af; clusters van Service Domains bakenen de componenten af.
Het boek richt zich hier op API's die functionaliteit en data van een applicatiecomponent ontsluiten. Het gaat niet om API's die geörkestreerde functionaliteit aan een partner of eindgebruiker aanbieden. Volgens het boek zijn het juist de eerste soort API's die de wendbaarheid van de tweede soort mogelijk maken. BIAN kan zo dienen als Reference Architecture voor het applicatielandschap van een bank.
Classificeren via Action Terms
Elke Service Operation voert precies één Action Term uit, en die termen vallen in vier categorieën. De granulariteit van de eigen API blijft een keuze van de bank.
Veelgestelde vragen
Nee, in het boek bestaat geen document met de naam 'API classification guideline'. De classificatie die BIAN wel kent, is die van de Action Terms, aangevuld met een stappenaanpak voor wie zelf API's afbakent. Zoek je een richtlijn, lees dan paragraaf 2.7.1 en paragraaf 8.4 samen, want die twee vormen het antwoord.
Het boek vermeldt geen versienummer bij de Action Term-lijst zelf. De lijst staat in Tabel 25 van BIAN 2nd Edition. Wie een specifieke versie nodig heeft, controleert dat bij BIAN. Leid uit het boek dus niet af dat de lijst vaststaat of dat er latere uitbreidingen zijn.
Op het BIAN API Portal, binnen het API Sandbox Platform met de Semantic API-catalogus. Per Service Domain staan daar Semantic API Endpoints als RESTful API-specificaties, voor een groeiend aantal Service Operations. De daaruit gegenereerde Swagger Files dienen als codestub waarmee ontwikkelaars hun eigen JSON-specificatie starten.
BIAN 2nd Edition – A framework for the financial services industry is bedoeld voor architecten en ontwerpers in de financiële sector die BIAN willen toepassen. Begin met paragraaf 2.7 voor Service Operations en Semantic API's. Lees daarna paragraaf 8.4 voor de stappenaanpak naar eigen API's. De standaardpagina bij Van Haren Group geeft meer context.
