Vervangen BAG Bevragen 2009 met Nieuwe BAG 2.0 API

[mdh]

Hallo allemaal,

In onze applicatie maken wij gebruik van de BAG bevragen 2009 service. Hiermee halen we op basis van een postcode en huisnummer het verblijfsobject en de gerelateerde panden op. Aangezien deze service vervangen gaat worden met de BAG 2.0 API ben ik aan het uitzoeken hoe we deze nieuwe API moeten implementeren. Ik loop hierbij tegen een aantal vragen aan:

• Wat is de correcte documentatie van de BAG 2.0 API?
  Als ik de links op de website van heet kadaster volg kom ik uit op een github pagina (GitHub - lvbag/BAG-API: Welkom op het platform waar de technische documentatie over de BAG API Individuele Bevragingen gepubliceerd wordt.). Hier staat een link naar een swagger pagina met de titel ‘IMBAG API - van de LVBAG’ met versie nummer 0.1. Is dit de officiële documentatie?

Mijn overige vragen gaan er vanuit dat bovenstaande documentatie de juiste is.

• Beperkte set aan operaties
  In onze case heb ik een operatie nodig waarmee ik op basis van een postcode een verblijfsobject object op te halen, zodat ik het id heb en vervolg calls kan doen. Ik had gehoopt dat deze operatie zou bestaan: GET /verblijfsobjecten?postcode=3361AN&huisnummer=50, maar ik kom iets dergelijks niet tegen. Zie ik iets over het hoofd? En zo nee, komt deze operatie binnenkort?

• Geen restful implementatie
  Het viel mij op dat de operaties niet restful geïmplementeerd zijn en dat er POST operaties gebruikt worden waarbij de body gebruikt wordt om parameters mee te geven. Gebruikelijk is om een GET operatie te gebruiken en de parameters in het path mee te geven. Zijn deze operaties nog in ontwikkeling of blijft dit zo?

• Wat is de status van de API?
  Op de website van het kadaster staat vermeld dat de productie versie van de API per maart 2020 beschikbaar zal zijn. Uit de bovenstaande documentatie blijkt echter dat er alleen maar een testversie beschikbaar is en dat de API’s nog in ontwikkeling zijn. Wanneer wordt de eerste versie gepubliceerd die niet meer wordt gewijzigd?

Alvast bedankt!

[NicoleKortoomsBAG]

Hallo mdh,

1. Op de githubpagina zijn onder het item ‘documentatie’ de laatste versies van de productmatrix als de productspecificatie beschikbaar. Met de ontwikkeling van de API is geconstateerd dat hierin nog een aantal minimale wijzigingen moet worden doorgevoerd.
   De link gaat naar de recente versie van de yaml van verblijfsobjecten die in ontwikkeling is. Op dit moment is deze nog niet definitief. De gehele yaml is ook beschikbaar onder ‘technische specificatie’
2. Deze specifieke operatie is niet voorzien. Met de combinatie postcode huisnummer kan direct de nummeraanduiding worden bevraagd waarmee vervolgcalls kunnen worden gedaan. Daarnaast wordt het mogelijk om met postcode huisnummer met de api object plus relaties te bevragen waarbij naast het object nummeraanduiding ook de gegevens van het verblijfsobject kunnen worden opgevraagd.
3. De meeste endpoints ondersteunen de GET operatie. Er zijn een aantal endpoints die ook de POST operatie ondersteunen.
   Wij volgen de NL API Strategie.
   Volgens par. 11.2 van de NL API Strategie Designrules Extensions (zie API Designrules Extensions (Nederlandse API Strategie IIb)), wordt de geometrie waarmee gezocht moet worden doorgegeven via een request body en niet via query parameters (oftewel in de URI).
   Mogelijk dat de specificatie hierin nog iets wijzigt.
4. Het is nog steeds het streven de eerste bevragingen vanuit de matrix in maart live te zetten en deze de komende tijd verder uit te breiden.

Groeten Nicole