VERA-OpenAPI

Inhoud

• Inleiding
• Viewers
• Toelichting
• Definities
• Toepassing
• Implementatiestandaarden
• Referentiedata

Inleiding

De mappen Informatiedomeinen en Ketenprocessen bevatten alle OpenAPI-specificaties (YAML). Alle overige bestanden in deze repo (in de root en in map 'docs') zijn enkel bedoeld voor documentatie en horen niet bij de opleverset. Op deze pagina staat een toelichting op de totstandkoming en toepassing van de API's.

Viewers

Hieronder staan links naar SwaggerUI views op de API's. Er zijn API's voor de gevensmodellen horend bij Informatiedomeinen en Ketenprocessen. Zie ook de toeliching hieronder.

:bulb: Tip: in Markdown worden links niet in een nieuwe pagina geopend. Als je een view opent, navigeer dan terug om weer op deze pagina te komen.

Ketenprocessen

Informatiedomeinen

Gebruik VERA OpenAPI - Ketenproces Onderhouden Eenheden

Het ketenproces Onderhouden Eenheden is samen met Ketenstandaard uitgewerkt en uitgebreid beschreven op de WIKI van Corponet. Dit ketenproces vormt de basis voor de berichten zoals opgenomen in de VERA OpenAPI-specificatie. Door de bundeling van kennis van beide organisaties is een proces tot stand gekomen die zowel voor de interne organisatie van de corporatie hanteerbaar is als ook in samenwerking met externe partijen zoals aannemers en onderhoudsbedrijven.

De VERA OpenAPI-specificaties zijn bedoeld voor de uitwisseling van data tussen de interne systemen van de corporatie. Het bedrijfsproces Klantbediening binnen de corporatie kan bijvoorbeeld ingevuld zijn door een systeem die data uitwisseld met het onderhoudsysteem van de corporatie. Ook zijn er corporaties met een eigen onderhoudsdienst met vakmannen die (een deel van) het onderhoud van het eigen bezit verzorgen. In alle gevallen dat er uitwisseling plaatsvindt tussen de interne systemen van de corporatie kan dus gebruik gemaakt worden van VERA OpenAPI.

Voor berichtuitwisseling met externe systemen van leveranciers zal gebruik gemaakt moeten worden van de DICO-berichten welke door Ketenstandaard wordt uitgegeven. Samen met VERA worden nieuwe DICO-berichten uitgewerkt die in lijn worden gebracht met de VERA OpenAPI-berichten zodat beide standaarden op elkaar aansluiten en compatibel met elkaar zijn. Voor de beschikbaarheid van de DICO-berichten verwijzen we naar de site van Ketenstandaard: https://ketenstandaard.nl/standaard/dico/

Toelichting

VERA heeft een alles omvattend gegevensmodel en gegevensmodellen per Ketenproces. De gegevensmodellen per Ketenproces bevatten alleen die entiteiten - en per entiteit alleen die attributen - uit het alles omvattende model, die een rol spelen binnen de procescontext. De entiteiten uit alle modellen zijn onderverdeeld in Informatiedomeinen. Een Informatiemodel bevat functies met een sterk onderlinge cohesie.​

We leveren OpenAPI-specificaties op voor zowel de Informatiedomeinen als voor de Ketenprocessen. Hiervoor hanteren we onderstaande regels: ​

• We gebruiken OpenApi 3.0 om overerving (OO) op te lossen (oneOf/allOf). Afgeleide klassen zijn alleen opvraagbaar via de basis-entiteit (ook wel aangeduid met superentiteit). ​

• Voor de Ketenprocessen leveren we per model een API-specificatie.​

• Voor het alles omvattende model leveren we per Informatiedomein een API-specificatie.​Hierin zijn alle entiteiten een bericht.

• Zelfde entiteitstypen kunnen binnen hetzelfde Ketenprocesmodel per bericht een andere definitie hebben.​

• In de API-specificatie van een Ketenproces worden alle afhankelijkheden opgenomen, ongeacht het Informatiedomein waartoe ze horen, met uitzondering van entiteiten uit Informatiedomein-API's die zonder restrictie gebruikt worden. Die worden als referentie (URI) opgenomen en moeten dus met aparte calls opgehaald worden. Uitzondering hierop vormen de entiteiten uit Informatiedomein Algemeen (Referentiedata, Sturingslabels, etc.), die worden wel opgenomen in iedere API.

• Voor een API-specificatie van een Informatiedomein geldt dat verwijzingen naar resources uit andere Informatiedomeinen niet embedded opgenomen worden, maar als referentie (URI). Hiervoor geldt het architectuurprincipe dat systemen uit verschillende Informatiedomeinen zich via API’s verbinden.​

• In de API-specificaties worden voor sleutelvelden van een entiteitstype (de kerngegevens) nieuwe entiteitstypen gegenereerd met als naam de naam van de entiteit gevolgd door '-sleutels'.

• Ook Informatiedomein Algemeen heeft een eigen API-specificatie.​

• Enumaraties: de wens is om referentiedata voor soorten van afgeleide klassen als enumeratie op te nemen (bijvoorbeeld: relatie.soort, overeenkomst.soort)

• Metadata (limiet aantal entiteiten in response, verzendende organisatie, tijdstip bericht, etc.) zit niet in de 'payload' maar wordt in de header meegestuurd. De headers worden altijd met een prefix aangegeven namelijk met X-headernaam, bijv. 'X-Stuurgegevens-TijdstipBericht'.

• Voor ophaal acties (GET operaties) op de verschillende klasses (bijv. Betalingsregeling) kunnen verschillende parameters meegestuurd worden om te kunnen sorteren op basis van het aantal (bijv. aantal betalingsregelingen) dat in het response wordt getoond. Dat kan met een parameter 'pagina' in de querystring of met de 'X-Parameters-Pagina' header. In beide gevallen kan een getal worden opgegeven om zo direct een specifieke pagina retour te krijgen. Afhankelijk van een optionele 'X-Parameters-AantalPerPagina' verschilt het aantal pagina's dat een verzoek teruggeeft.

Alle ophaal acties ondersteunen daarnaast een cursor als querystring parameter. Hiermee kan een volgende pagina opgehaald worden. Deze cursor is te onttrekken uit een eerder response op de API. In dat response zit een X-Parameters-Cursor header die gebruikt kan worden om een volgende pagina op te halen.

• In de VERA standaard en dus ook de VERA Open API is veel informatie aanwezig. Op de VERA Wiki is inzicht te vinden in deze informatie. Naast deze uitgebreide documentatie is middels onderstaande URL een Excel bestand te downloaden om eenvoudig als gebruiken te kunnen zoeken naar specifieke termen. De Excel bevat alle data over de verschillende informatiedomeinen, ketenprocessen en referentiedata.

https://github.com/vereniging-corponet/vera-openapi/blob/main/docs/brongegevens.xlsx

• Voor de VERA API wordt aangesloten bij de Semantic versioning 2.0.0. Een gedetailleerde uitleg over de impact van de versies die uigebracht worden door VERA is hier te vinden: https://www.coraveraonline.nl/index.php/VERA_Release_en_versiebeleid

• in de API's van de ketenprocessen worden entiteiten geprefixt met de naam van de resource

Toepassing

VERA defineert Informatiedomeinen als geheel van gerelateerde informatieobjecten en informatiebronnen. Een Informatiebron wordt ook wel aangeduid als Kernpakket. VERA levert hiervoor per Informatiedomein een API.

Daarnaast kent VERA zogenaamde ketenprocessen. Het subsysteem dat een ketenproces implementeert kan gegevens uit meerdere Informatiedomeinen nodig hebben. Hiervoor levert VERA per ketenproces een API.

Implementatiestandaarden VERA

Naast de definitie van informatiedomeinen en ketenprocessen biedt VERA ook steeds meer standaarden rondom de implementatie van de gegevensuitwisseling. Deze standaarden bieden steeds meer zekerheid over de interoperabiliteit tussen systemen. Vanaf VERA 4.1.3 is de standaard rondom het gebruik van sleutels van objecten verder (id, idExtern, ..) uitgewerkt. Zie hiervoor de WIKI https://www.coraveraonline.nl/index.php/Richtlijnen#Identificatie_van_gegevensobjecten.

Data API's

• In de VERA-standaard en dus ook de VERA Open API is veel informatie (data) aanwezig. Op de VERA Wiki is inzicht te vinden in deze informatie. Naast deze uitgebreide documentatie is middels onderstaande URL een Excel bestand te downloaden om eenvoudig als gebruiken te kunnen zoeken naar specifieke termen. De Excel bevat alle data over de verschillende informatiedomeinen, ketenprocessen en referentiedata. Het bestand is de bron van de totstandkoming van alle API's.

https://github.com/vereniging-corponet/vera-openapi/blob/main/docs/brongegevens.xlsx

Referentiedata

De VERA-standaard kent attributen die geen vrije waarde mogen hebben, maar alleen een waarde uit een waardeverzameling. Deze verzamelingen/lijsten zijn door VERA vastgelegd als Referentiedata. Lees meer hierover op: https://www.coraveraonline.nl/index.php/Referentiedata

Referentiedata bevindt zich in een eigen repository en wordt onafhankelijk van de OpenAPI-specificaties gereleased, zie: https://github.com/Aedes-datastandaarden/vera-referentiedata

Een overzicht van welke lijst gekoppeld is aan welke entiteit (cross reference) staat hier: https://aedes-datastandaarden.github.io/vera-openapi/referentiedatacrossreference.html

Let op: niet alle lijsten worden geleverd door VERA. In sommige gevallen wordt er verwezen naar bestaande lijsten, zoals ISO taal- en landcodes en anders heeft de leverancier vrijheid eigen codes te gebruiken.