Terugmelding API beschikbaar in acceptatie-omgeving

De afgelopen jaren is het terugmelden op de Basisregistraties Grootschalige Topografie (BGT), Topografie (BRT) en Adressen en Gebouwen (BAG) veel eenvoudiger geworden door de terugmeldmogelijkheden in Verbeter de Kaart en de BAG viewer. Vanaf 2019 wordt het ook mogelijk om vanuit andere systemen onjuistheden door te geven door middel van de ‘Terugmelding API’.

De terugmelding API is nu beschikbaar in de acceptatie-omgeving voor testdoeleinden. Via de API wordt het mogelijk om direct een terugmelding te doen op de BGT, BRT, BAG en KLIC (bèta). Ook is het mogelijk om terugmeldingen te bekijken door deze op te halen. Uiteraard zullen meldingen in de acceptatie-omgeving niet daadwerkelijk doorgestuurd worden naar de bronhouder. De acceptatieomgeving van de API is beschikbaar via de volgende URL:

https://api.acceptatie.kadaster.nl/tms/v1/terugmeldingen

De API is beveiligd met een API key. Om toegang te krijgen tot de API dient u het API key aanvraag formulier in te vullen: Aanvragen API-key voor Terugmelding API. Er wordt dan binnen enkele werkdagen een API key aangemaakt en naar u opgestuurd.

Documentatie over de API kunt u downloaden via de volgende URL in Open API Specification 3 (OAS3) als JSON formaat: https://verbeterdekaart.kadaster.nl/api-doc/terugmeldingapi.json
Een voorbeeld van de gewenste (Geo)JSON structuur en vulling van de velden vindt u hier: https://verbeterdekaart.kadaster.nl/api-doc/TerugmeldingGeneriekVoorbeeld.json

Ingeschoten terugmeldingen op de BGT en BRT zijn direct te bekijken op de acceptatie-omgeving van Verbeter de Kaart: https://verbeterdekaart.acceptatie.kadaster.nl/.

Let op: Omdat de API en documentatie in een acceptatie-omgeving staan, zit hier geen beveiligd certificaat op. De waarschuwing kunt u veilig negeren.

Ontwikkelproces API
Zowel de API als de documentatie zijn nog in ontwikkeling. Er zullen de komende periode nog wijzigingen worden doorgevoerd, waarbij het ook mogelijk is dat er breaking changes worden doorgevoerd.
Uiteraard is uw feedback bij deze verdere ontwikkeling erg belangrijk! We horen graag wat u opvalt aan de huidige API hier op het Geoforum, zodat we hierop onze ontwikkelingen kunnen aanpassen.

Livegang productie-omgeving
Het streven is om in de eerste helft van 2019 de productie-omgeving van de API te publiceren. Voor KLIC zal er dan een gefaseerde livegang van deze API plaatsvinden.

Known issues
De acceptatie omgeving kent zijn beperkingen. Daarnaast is de API nog in ontwikkeling. Houdt daarom met het volgende rekening:

  • Omdat de API en documentatie in een acceptatie-omgeving staan, zit hier geen beveiligd certificaat op. De waarschuwing kunt u veilig negeren.
  • Het is niet mogelijk om vanuit de acceptatieomgeving e-mails te sturen. Er zullen dus geen ontvangstbevestigingen van nieuwe terugmeldingen gestuurd worden, wanneer er een e-mailadres wordt opgegeven.
  • Het is nog niet mogelijk om terugmeldingen met de status ‘Geparkeerd’ of ‘Doorgestuurd naar andere basisregistratie’ als filter op te halen.
3 likes

Het verband tussen de versie (1.0.1) van de API en de verschillende fasen (zie post Terugmeldingen API - ontwerp - Terugmeldvoorzieningen - Geoforum) is mij niet geheel duidelijk.

Fase 1 zou alleen een GET methode ondersteunen en fase 2 zou ook een POST methode ondersteunen, deze versie van de API ondersteund een GET en een POST methode maar de versie is 1.0.1.

Omdat er in fase 2 sprake is van toegevoegde functionaliteit had ik verwacht dat of de minor of de major van de versie was opgehoogd.

Goed punt! We hebben ervoor gekozen om de GET en POST functionaliteit tegelijk naar buiten te brengen. Daarnaast hebben we besloten om met versionering te beginnen vanaf het moment dat we extern bereikbaar zijn. Anders zouden we eigenlijk /v3/ nu lanceren.

Er zit geen directe relaties tussen de aangegeven fases en de API versie. De fases zijn meer een indicatie qua volgorde wanneer welke functionaliteit beschikbaar is.
We gaan nu eerst de functionaliteit uit de GET en POST fase robuuster maken. De API-versie die straks in de productie-omgeving staat, zal dus vermoedelijk hoger zijn dan 1.0.1.

1 like

De documentatie van de API (OAS3) is nu ook te vinden via: https://verbeterdekaart.kadaster.nl/api-doc/terugmeldingapi.json en https://verbeterdekaart.kadaster.nl/api-doc/TerugmeldingGeneriekVoorbeeld.json.

Verder als aanvulling op de vorige vraag: de genoemde versie is de versie van de documentatie (het OAS3 bestand), niet van de API. De versie van de API kunt u zien bij het API-Version veld.

Er is een kleine update gedaan in de genoemde API documentatie: versie 1.0.3 is beschikbaar. Met name in het genoemde TerugmeldingGeneriekVoorbeeld.json is aangepast dat voortaan bronhoudercode en bronhoudernaam niet meer aangeleverd dienen te worden.

Het is zover! De laatste wijzigingen aan de Terugmelding API hebben plaatsgevonden en we zijn van plan om de Terugmelding API op 18 september in productie te nemen. De belangrijkste wijzigingen hebben plaatsgevonden in de foutafhandeling.

Bekijk de laatste OAS3 documentatie via:
https://verbeterdekaart.acceptatie.kadaster.nl/api-doc/terugmeldingapi.json

Vraag een API key aan via:
https://formulieren.kadaster.nl/aanvragen_api_key_terumelding_api

API:
https://api.acceptatie.kadaster.nl/tms/v1/terugmeldingen

Uiteraard zal de acceptatie omgeving live blijven voor testdoeleinden wanneer de API in productie staat.

Vragen/opmerkingen kun je in dit topic kwijt.

1 like