Update BAG & BRT Top10NL & BRK-DKK REST API's

[jasperroes]

Zoals sommige van jullie al gemerkt hebben we vanochtend de BAG en de BRT Top10NL REST APIs (te vinden op bag.basisregistraties.overheid.nl en brt.basisregistraties.overheid.nl) gemigreerd naar onze nieuw omgeving. De API specificaties zijn daarbij niet aangepast, onze verwachting is dat bestaande implementatie over het algemeen blijven functioneren. We hebben inmiddels al wel een bug opgelost in de nieuwe BAG API, er eentje opgenomen in de lopende sprint en het is niet uit te sluiten dat jullie nog additionele bugs vinden. We zullen deze zo snel mogelijk oppakken en oplossen.

In de beide API’s zijn daarnaast een heel aantal oude bugs nu direct verholpen en ook een aantal onvolkomendheden opgelost. De beide APi’s zijn daarnaast nu voorzien van recente data. De BAG API wordt vooralsnog 1x per maand van nieuwe data voorzien, de BRT Top10NL API wordt 5x per jaar bijgewerkt nadat de Top10NL dataset door de BRT is geupdate. Voor de BAG API hopen we uiterlijk eind kwartaal 3 de update frequentie te verhogen naar 1x per dag.

In de komende weken zal ook de BRK-DKK API (te vinden op brk.basisregistraties.overheid.nl) gemigreerd gaan worden, hierbij zal dan ook nieuwe data geladen zijn (in plaats van de inmiddels zeer oude dataset).
Update 16 juli: de data achter deze API zal op verzoek van de data-aanbieder voorlopig niet maandelijks bijgewerkt worden. We zijn wel in gesprek met de data-aanbieder om ook bij deze API de updatefrequentie te verhogen naar 1x per dag.

Mochten julie nog tegen problemen aanlopen in de BAG of BRT Top10NL API laat dat dan weten in dit topic. Wij zullen bugs dan zo snel mogelijk oplossen of aangeven hoe het probleem verholpen kan worden.

[jasperroes]

De BRK-DKK API is inmiddels ook gemigreerd, deze heeft nu dus recente data beschikbaar en de data zal 1x per maand bijgewerkt worden. Mocht je problemen ondervinden bij het gebruik van de BRK-DKK API die er tot gisteren niet waren laat het ons dan weten.

[jasperroes]

@antonydj Als antwoord op je vraag in dit topic: https://geoforum.nl/t/bag-api-v1-1-geometrie-pages-blijven-verhogen

We zijn ervan op de hoogte dat er altijd een next link is, ook als er geen pagina met resultaten meer is. We gaan kijken of we de next link conditioneel kunnen maken. Mocht dat niet lukken dan passen we de API specificatie aan om deze in lijn te brengen met de daadwerkelijke situatie.

[antonydj]

Alvast bedankt voor het snelle antwoord!
is het dan ook een correcte assumptie dat als de respons leeg is op een pagina, er geen data meer zal voorkomen op de volgende pagina’s?

[jasperroes]

Ja, dat is een correct aanname. Zodra je een lege pagina krijgt, of het aantal resultaten op een pagina is lager dan het aantal resultaten per pagina dat je opgegeven hebt zal er geen data meer voorkomen op de volgende pagina’s.

[miloman]

Mooi dat we dit topic hebben gevond, want wij (ABN AMRO) lopen tegen een aantal onverwachte wijgingen aan. oals hier genoemd de gevulde ‘next’ tag, maar erger nog lijkt het ‘filteren’ op huisnummer anders te werken dan voorheen, waardoor onze real estate applicatie nagenoeg stilstaat
Daarnaast andere waardes in status (nu met spatie, voorheen zonder), waardoor selecties mislopen… Al met al een serieus issue voor onze organisatie… We hebben inmiddels een incident laten aanmaken, maar we zouden heel graag zien dat deze wijziging wordt teruggedraaid…

[jasperroes]

Hallo @miloman, de wijziging terugdraaien is voor ons geen optie. De hele migratie is er namelijk op gericht om een stabiele service te kunnen blijven bieden op een stabiel onderliggend platform, de oude API terugzetten levert daarin teveel risico’s op. Daarnaast konden we op de oude omgeving al heel lang geen updates meer doorvoeren van de data waardoor er meer en meer vragen kwamen over missende objecten in de dataset.

We willen uiteraard wel graag helpen bij het oplossen van de problemen waar jullie nu tegenaan lopen. Je geeft aan dat het filteren op huisnummer nu anders werkt dan voorheen. Zou je de call die jullie doen naar de API hier willen posten en aan willen geven wat de oude response was en wat jullie nu krijgen. Daarmee kunnen wij dan kijken of het kunnen reproduceren en mogelijk ook aanpassen.

Wat betreft de next links: we gaan kijken of we dan aan kunnen passen, is helaas geen hele eenvoudige aanpassing.

Wat betreft de status: we gebruiken nu de exacte waarde zoals die in de BAG dataset is opgenomen, hiervoor waren de statussen inderdaad net iets anders. Dit kunnen we niet meer aanpassen.

[jasperroes]

Voor de BAG API is het trouwens goed om te weten dat deze vervangen gaan worden voor een nieuwe API, in de huidige planning van de BAG is opgenomen dat de BAG REST API v1 (die nu gemigreerd is) in maart 2021 uitgefaseerd wordt. De planning van de oplevering van de nieuwe BAG REST API is te vinden op: https://zakelijk.kadaster.nl/producten-2.0

[miloman]

Ok @jasperroes, dat is jammer want dat gaat ons een hoop haastwerk opleveren We hebben een samengestelde API laten bouwen op onze Enterprise Service Bus, ongeveer een jaar geleden, die op basis van postcode huisnr alle VBO’s levert in de panden die op die pc/hnr zijn gevonden. Ik ben zelf zijdelings betrokken geweest, maar alle mensen die hier aan gewerkt hebben zitten weer eldersof zijn weg. Ik heb gister een design van deze API gekregen, duik ik zo in. Als ik onze ESB mensen goed begrijp, gaat het nu mis doordat de vervolgaanroep een lege response teruggeeft, en de samengestelde API helemaal niks meer teruggeeft (ik geeft toe, ook niet handig van ons…).
Daarnaast is er geprogrammeerd om bepaalde statussen te filteren, en dat gaat ook mis nu er andere waarden hierin voorkomen. Verzoek om in het vervolg dit goed te communiceren (of hebben we wat gemist, is ook niet ondenkbaar). Ik doe een stukje van de code hierbij, kan je zien wat voor impact dat heeft. Dit ESB team heeft een eigen backlog, dus het gaat ons veel moeite kosten om dit zsm aangepast te laten krijgen…

Ik zit zelf zo bij het webinar over 2.0, dus dat komt goed. We kunnen tijdig eea in gang zetten.
Ik vrees dat ik geen oude responses van de huisnummer aanduiding boven water kunnen krijgen, enige wat er gelogd wordt is het samengestelde eindresultaat van de ESB API…

[jasperroes]

Nee, jullie hebben niets gemist. We hebben (te) laat gecommuniceerd over de migratie en omdat we geen aanpassingen hebben gemaakt in de API specificatie zelf hadden we onterecht aangenomen dat de migratie voor onze eindgebruikers zonder problemen zou verlopen.

Voor zover wij kunnen nagaan is er aan het opvragen van de huisnummer aanduiding niets aangepast, we kunnen daar zonder voorbeeld niet heel makkelijk dieper in duiken.

[jasperroes]

@miloman Om te helpen met de wijzigingen in de statussen hebben we een overzicht gemaakt met de oude statussen en de nieuwe.

                      | Was in API                             | Is geworden in API
--------------------- |----------------------------------------|---------------------------------------------
StatusWoonplaats      | WoonplaatsAangewezen                   | Woonplaats aangewezen
                      | WoonplaatsIngetrokken                  | Woonplaats ingetrokken
StatusNaamgeving      | NaamgevingUitgegeven                   | Naamgeving uitgegeven
                      | NaamgevingIngetrokken                  | Naamgeving ingetrokken
StatusPand            | BouwvergunningVerleend                 | Bouwvergunning verleend
                      | NietGerealiseerdPand                   | Niet gerealiseerd pand
                      | BouwGestart                            | Bouw gestart
                      | PandInGebruik_nietIngemeten            | Pand in gebruik (niet ingemeten)
                      | PandInGebruik                          | Pand in gebruik
                      | SloopvergunningVerleend                | Sloopvergunning verleend
                      | PandGesloopt                           | Pand gesloopt
                      | PandBuitenGebruik                      | Pand buiten gebruik
StatusPlaats          | PlaatsAangewezen                       | Plaats aangewezen
                      | PlaatsIngetrokken                      | Plaats ingetrokken
StatusVerblijfsobject | VerblijfsobjectGevormd                 | Verblijfsobject gevormd
                      | NietGerealiseerdVerblijfsobject        | Niet gerealiseerd verblijfsobject
                      | VerblijfsobjectInGebruik_nietIngemeten | Verblijfsobject in gebruik (niet ingemeten)
                      | VerblijfsobjectInGebruik               | Verblijfsobject in gebruik
                      | VerblijfsobjectIngetrokken             | Verblijfsobject ingetrokken
                      | VerblijfsobjectBuitengebruik           | Verblijfsobject buiten gebruik
TypeOpenbareRuimte    | Weg                                    | Weg
                      | Water                                  | Water
                      | Spoorbaan                              | Spoorbaan
                      | Terrein                                | Terrein
                      | Kunstwerk                              | Kunstwerk
                      | LandschappelijkGebied                  | Landschappelijk gebied
                      | AdministratiefGebied                   | Administratief gebied

[miloman]

Super, dat helpt! Ons probleem blijkt te ontstaan doordat de next link uit nummeraanduiding verwijst naar een lege pagina. Daardoor wordt er geen output meer doorgeven (ook alle voorgaande pages worden weggegooid…). Dat was niet zo in de vorige versie. Maar snap ook dat dit een erg slordige manier van programmeren is geweest aan onze kant… Daarnaast lopen we tegen nog wat technische dingen aan in de locatieserver, maar weet niet of dat op dit forum hoort…
Maar dank vast voor je ondersteuning!

[jasperroes]

Fijn dat het helpt. We zijn nu trouwens ook druk bezig om te kijken of we de next link problemen kunnen verhelpen, ik durf nog geen garanties te geven maar we zijn er wel druk mee bezig.

Locatieserver mag ook op dit forum, maar dan is het wel handig om even een los topic aan te maken.

[RobinTopper]

@antonydj @miloman Er is zojuist een nieuwe versie van de BAG API in productie gezet waarbij de next link null is als er zeker geen volgende pagina is.

[rubenlinde]

Alleen nu is dus de quick fix die wij vanochtend hebben uitgerold natuurlijk weer omgevallen, is dit de laatste aanpassing die jullie vandaag doen op de productie omgeving?

[RobinTopper]

In ieder geval de laatste backwards incompatible change.

[rubenlinde]

De vorige change waarmee alles omviel was volgens het kadaster ook backwardscompatible, en heeft ons vanochtend toch echt wat tijd gekost

Het nu weer naar null zetten trouwens ook.

[miloman]

Je doet je naam eer aan We gaan eea uitproberen. Bij een testaanroep zie ik idd dat het werkt (c.q. niet aanwezig is)!

[Roel1]

We zien dat na de migratie properties zonder waarde expliciet worden opgenomen in de response met value null. Onze software, die we hadden gegenereerd op basis van de originele yaml files, kan daar niet tegen. Dat wordt veroorzaakt doordat in de nieuwe versie van de yaml files nullable is true is opgenomen terwijl die in de oude versie ontbrak. We zien in de nieuwe verse van de BAG API (versie 2.0) deze lege properties ook niet terug in de response en ik meen ook begrepen te hebben dat het een bewuste keuze was deze niet in de response op te nemen. Is hier sprake van voortschrijdend inzicht of is dit een bug? Onze software is in gebruik bij een groot aantal klanten, dus we hebben met deze wijziging een serieus probleem.