gemma-zaken
gemma-zaken copied to clipboard
VNG-Realisatie
Als API Designer wil ik dat er in de OAS-schema's geen componenten worden gedupliceerd
zodat:
- objectdefinities niet uit elkaar gaan lopen,
- het standaardisatieproces beter kan worden gefaciliteerd als API's hergebruik maken van dezelfde OAS-libraries,
- de verschillen beter te zien zijn bij nieuwe oas-ontwerpen.
Als voorbeeld heb ik een aantal refactorings doorgevoerd in de Klantinteractie API: zie hier in mijn eigen fork. In Redoc is te zien dat deze refactorings geen invloed hebben op het eindresultaat.
De hergebruikte componenten van de ZGW API's worden gedeeld in deze common file:
https://github.com/HenriKorver/gemma-zaken/blob/master/api-specificatie/DESIGN/common/common.yaml
Je kunt deze file ook met Swagger bekijken.
Ter info:
Bij HaalCentraal hebben ze deze functionaliteit ingevuld met https://raw.githubusercontent.com/VNG-Realisatie/Haal-Centraal-common/master/api-specificatie/common.yaml.
Dat kan wanneer de API's door dezelfde partij geboden worden. Het lijkt me lastiger om zo'n soort library te gebruiken voor API's die door een leverancier van een systeem geboden moeten worden. Dan kom je toch weer een beetje richting een StUF sectormodel.
Op zich is er niets op tegen om een gezamelijke library van types ed. te hebben maar aan de andere kant, hoeveel moeite is het om die types op te nemen in een OAS voor een bepaalde API? Worden de API's dan niet te afhankelijk van elkaar?
Ik denk dat het goed is om dit te doen aangezien we daarmee verschillen tussen de verschillende API's op dit punt voorkomen. Het kost wellicht niet veel moeite om de types gewoon in de OAS op te nemen maar een foutje is zo gemaakt en besluiten we om het type in de common.yaml aan te passen dan is die wijziging ook meteen doorgevoerd in alle API's. In die zin worden API's afhankelijk van elkaar, wijzigingen in de common.yaml kunnen verdragend zijn en het beheer van de common.yaml is dus een serieuze zaak is. De in de common.yaml op te nemen componenten moeten dus goed doordacht zijn. Dit soort afhankelijkheden hoeven niet meer te spelen in de API definities die aan de leveranciers geleverd worden. Je kunt immers, net als bij HaalCentraal, geresolvde yaml bestanden beschikbaar stellen waarin dit soort verwijzingen zijn opgelost.
De vergelijking met een StUF sectormodel gaat n.m.m. niet op omdat in de StUF sectormodellen entiteiten waren opgeslagen. In de common.yaml zullen, naar mijn verwachting, slechts types en veelgebruikte attributen opgeslagen worden.
Bij HaalCentraal hebben ze deze functionaliteit ingevuld met https://raw.githubusercontent.com/VNG-Realisatie/Haal-Centraal-common/master/api-specificatie/common.yaml.
Ja daar heb ik natuurlijk naar gekeken en alvast de naam van de include file (common.yaml) overgenomen als eerste stap in de harmonisatie van de VNG API's. Het doel is dat alle VNG API's gebruik maken van dezelfde common OAS-library. Uiteindelijk zou een dergelijke library ook landelijk aangeboden kunnen worden via het Kennisplatform API's als onderdeel van de API Strategie.
Worden de API's dan niet te afhankelijk van elkaar?
Niet noodzakelijk, je kunt zoals Robert zegt met een resolver tool altijd zorgen dat de links naar de include files worden platgeslagen. Dat doen ze nu bij HaalCentraal.
Sidenote: Imports en inheritence is nog niet echt lekker verwerkt in OAS 3 en zelfs niet in OAS 3.1. Het werkt maar het OAS-team is nog niet helemaal happy met de huidige werking omdat de included OAS-yaml files geen geldige OAS files zijn.
Ik ben verdeeld over deze "feature" en ook hoe ver je hierin wil gaan. Op zich klinkt het namelijk goed en mijn eerste gedachte is positief, echter...
Er zal heel goed nagedacht moeten worden over:
- herbruikbare delen BINNEN dezelfde API (Bijv. sommige headers zoals
Accept-CRSdie alleen nodig is in geval het ZRC. Henri heeft hem hier in Common gestopt.) - herbruikbare delen OVER MEERDERE API's (Bijv. legacy resource: natuurlijk persoon, en headers die de API-stategie voorstelt zoals
API-versionenWarning) - welke delen je opneemt in ÉÉN herbruikbaar deel (Henri's voorbeeld neemt bijv. GeoJSON mee in Common maar ik zou dat apart doen omdat niet elke API gebruik maakt van GeoJSON)
Er zijn ook echt nadelen:
- Gedeelde OAS-delen aanpassen is HEEL TRICKY als je deze over meerdere API's gaat gebruiken. Je krijgt volgens mij zelfs versioning van zo'n gedeelde OAS waarbij verschillende OASen van API's naar verschillende versies van Common gaan wijzen.
- Juist met het CG-gedachtegoed "niet kopieren" ligt het hergebruik van componenten binnen een OAS niet voor de hand. We hebben nu een paar "legacy-compatability" oplossingen zoals NP, NNP, etc. binnen de API (waar het niet hoort).
Over de genoemde voordelen:
objectdefinities niet uit elkaar gaan lopen, de verschillen beter te zien zijn bij nieuwe oas-ontwerpen.
Check, dat is fijn.
het standaardisatieproces beter kan worden gefaciliteerd als API's hergebruik maken van dezelfde OAS-libraries,
Deze zie ik niet zo. Het standaardisatie proces zou mijn insziens op meta-nivieau (van uml tot tekstuele bullets of andere tool) en leidt tot een OAS die gestandaardiseerd wordt. Denk dat het voor het proces inderdaad niet nuttig is om alle foutmeldingen te herhalen, daarnaast zijn echter ook niet ALLE foutmeldingen voor elke resource gelijk :)
Uiteindelijk maakt het voor een ontwikkelaar allemaal niet heel veel uit.
Sidenote: Imports en inheritence is nog niet echt lekker verwerkt in OAS 3 en zelfs niet in OAS 3.1. Het werkt maar het OAS-team is nog niet helemaal happy met de huidige werking omdat de included OAS-yaml files geen geldige OAS files zijn.
Bij HaalCentraal lijkt de included OAS-yaml constructie prima te werken. Bovendien kun je het probleem dat de included file geen geldige OAS is oplossen met een simpel trucje, namelijk een dummy path toevoegen (bijv. ping).
Er zal heel goed nagedacht moeten worden over: ...
Eens dat we over de opsplitsing van include files goed moeten nadenken. Maar er zijn m.i. al snel een paar goede keuzes te maken. En zo ingewikkeld is het ook weer niet. Bovendien kunnen we op AGILE wijze simpel beginnen met het uitsplitsen van één of meer include-files en gaande weg leren wat de beste opdeling is. Dit lijkt me in ieder geval geen showstopper.
Gedeelde OAS-delen aanpassen is HEEL TRICKY als je deze over meerdere API's gaat gebruiken. Je krijgt volgens mij zelfs versioning van zo'n gedeelde OAS waarbij verschillende OASen van API's naar verschillende versies van Common gaan wijzen.
Kan inderdaad tricky zijn, maar het is natuurlijk de bedoeling om de gedeelde include files zo stabiel mogelijk te houden en zo weinig mogelijk te veranderen. En als je iets aanpast in de common file zoveel mogelijk backwards compatible zodat je de versie niet hoeft op te hogen.
Juist met het CG-gedachtegoed "niet kopieren" ligt het hergebruik van componenten binnen een OAS niet voor de hand. We hebben nu een paar "legacy-compatability" oplossingen zoals NP, NNP, etc. binnen de API (waar het niet hoort).
Ik zie dit niet als een nadeel. Zolang we te maken hebben met legacy-compatibiliteit oplossingen zullen include-files een prima middel zijn om de definities voor NP, NNP, etc te kunnen delen over verschillende API's. Op het moment dat het beloofde CG-landschap echt vorm begint aan te nemen kunnen we de include-files langzaam gaan ontmantelen tot kleinere eenheden.
Uiteindelijk maakt het voor een ontwikkelaar allemaal niet heel veel uit.
Dat hangt ervan af hoe je het bekijkt. De ontwikkelaar zal qua OAS geen verschil zien omdat hij/zij altijd beschikking zal hebben over de geresolvde versie waarin alle include files zijn platgeslagen (verdwenen). Maar deze aanpak zorgt er wel voor dat alle gedeelde OAS-definities (zoals foutmeldingen, headers, parameters, etc) over alle API's precies hetzelfde zijn en niet overal net weer iets anders. Ik denk dat elke developer dat enorm zal waarderen.
Ik zie het gebruik van include-files als een win-win situatie omdat je door gebruik te maken van de resolver altijd terug kunt naar de huidige situatie van één platte OAS-file.
Dus ik zou graag met de Klantinteractie API alvast willen beginnen deze nieuwe werkwijze te introduceren en als het werkt dan rustig opschalen naar de andere API's binnen de ZGW-familie.
Juist met het CG-gedachtegoed "niet kopieren" ligt het hergebruik van componenten binnen een OAS niet voor de hand. We hebben nu een paar "legacy-compatability" oplossingen zoals NP, NNP, etc. binnen de API (waar het niet hoort).
Ik begrijp deze opmerking niet. Hergebruik van componenten door ze in een gemeenschappelijke include-file te plaatsen ligt toch juist voor de hand?
Ik zou met een klein experiment willen beginnen zoals Henri voorstelt waarna we evalueren of het aan de verwachtingen voldoet.
