Wij zijn bezig met de upgrades van onze code rondom het afnemen van de BAG en BRK API's en het valt ons op dat er een verschil in release notes zijn. Kijkende naar de BRK API release notes (met name 1.3.0) dan is deze zeer goed gedocumenteerd rondom de wijzigingen in de objectenstructuur, algemene punten en wanneer van toepassing (zeker ook bij BRP) wijzigingen in features. Voor een afnemer is dit zeer nuttig om te hebben aangezien we anders de gehele objectenstructuur moeten doorlopen (genereren, vergelijken) in de hoop om dan alle wijzigingen te kunnen vinden, laat staan de algemene zaken zoals camel casing wijzigingen of feature wijzigingen. Met name de laatste twee kunnen per ongeluk niet worden gezien omdat het niet altijd een fout veroorzaakt.
Kijkende naar de BAG, krijgen we alleen een overzicht van aangepakte issues welke niet per se aangegeven welke wijzigingen er zijn gemaakt, met name met oog op objectenstructuur. Een voorbeeld uit 1.2.0 is 'Er worden nu adresregels geleverd met daarin het samengestelde adres.' welke gelukkig ons helpt, maar daar houdt het bij op. We kunnen nu niet met redelijke zekerheid zeggen dat alle wijzigingen zijn bezocht en zijn we toch verplicht om die vergelijking te doen.
Het is vanzelfsprekend dat de release notes ook fouten kunnen bevatten en we niet 100% vertrouwen erin moeten hebben, maar als ik kijk naar hoeveel tijd dit ons scheelt dan is dit zeer wenselijk om dit soort documentatie bij alle API's de standaard te maken.
Originally created by KayodeBakker (https://github.com/VNG-Realisatie/BAG-Gemeentelijke-wensen-tav-BAG-Bevragingen/issues/522):
Wij zijn bezig met de upgrades van onze code rondom het afnemen van de BAG en BRK API's en het valt ons op dat er een verschil in release notes zijn. Kijkende naar de BRK API release notes (met name 1.3.0) dan is deze zeer goed gedocumenteerd rondom de wijzigingen in de objectenstructuur, algemene punten en wanneer van toepassing (zeker ook bij BRP) wijzigingen in features. Voor een afnemer is dit zeer nuttig om te hebben aangezien we anders de gehele objectenstructuur moeten doorlopen (genereren, vergelijken) in de hoop om dan alle wijzigingen te kunnen vinden, laat staan de algemene zaken zoals camel casing wijzigingen of feature wijzigingen. Met name de laatste twee kunnen per ongeluk niet worden gezien omdat het niet altijd een fout veroorzaakt.
Kijkende naar de BAG, krijgen we alleen een overzicht van aangepakte issues welke niet per se aangegeven welke wijzigingen er zijn gemaakt, met name met oog op objectenstructuur. Een voorbeeld uit 1.2.0 is 'Er worden nu adresregels geleverd met daarin het samengestelde adres.' welke gelukkig ons helpt, maar daar houdt het bij op. We kunnen nu niet met redelijke zekerheid zeggen dat alle wijzigingen zijn bezocht en zijn we toch verplicht om die vergelijking te doen.
Het is vanzelfsprekend dat de release notes ook fouten kunnen bevatten en we niet 100% vertrouwen erin moeten hebben, maar als ik kijk naar hoeveel tijd dit ons scheelt dan is dit zeer wenselijk om dit soort documentatie bij alle API's de standaard te maken.