De API's

Er zijn vier API’s. Welke je nodig hebt, hangt af van wat je bouwt.

Beheer-API (connector)Alles wat de beheeromgeving en bl doen: gebouwen, systemen, producten, aanvragen, apps, bewijs, instellingen. Voor automatisering bij je eigen connector.

Gateway-API (apps)Wat je app aanroept om data te lezen en te sturen, bij de gateway van je eigen data plane.

Backend-API (systemen)Wat het systeem van een datahouder moet bieden: het Buildinglinks-protocol, dat de data plane aanroept.

Trust Authority-APIAanmelding, register, lidmaatschapsbewijzen, notaris. Voor wie een Trust Authority beheert.

Wie roept wat aan

Je app praat alleen met de gateway van je eigen data plane, met de sleutel van de app. Hoe dat werkt: Een app koppelen.
De data plane van een datahouder roept de backend-API van het eigen systeem aan, met de sleutel die bij de koppeling is ingesteld. Hoe dat werkt: Een systeem koppelen.
Jij, je scripts en bl gebruiken de beheer-API van je eigen connector, met een API-sleutel of na bl login. De rollen admin, operator en viewer bepalen wat mag; dat staat per operatie bij Beveiliging.
De protocollen tussen connectors (Dataspace Protocol, Decentralized Claims Protocol, Data Plane Signaling) staan ook in de beschrijving van de connector, gemarkeerd als protocol. Die roep je niet zelf aan; dat doen de connectors onderling.

Uit de code, en daarom actueel

Deze naslag is gegenereerd uit de code van de connector, de data plane en de Trust Authority (OpenAPI 3.1, in de repository onder docs/api/). Tests bewaken dat:

elke route die de diensten echt aanbieden in de beschrijving staat, of bewust is uitgezonderd met een reden, en andersom;
de beschrijving gelijk is aan wat de code genereert;
de data plane alleen paden aanroept die in de backend-API staan, en de gesimuleerde backend ze allemaal implementeert.

De beschrijvingen van de afzonderlijke operaties zijn in het Engels, zoals gebruikelijk bij API’s. Elke operatie van de beheer-API heeft ook een x-cli-veld met het bl-commando dat erbij hoort.