Terugmeldingen API - ontwerp

JWSjoukema · 7 december 2017 om 07:46

Via Verbeter de Kaart kunnen BGT, BRT terugmeldingen eenvoudig gedaan worden en via de BAG viewer kunnen BAG terugmeldingen makkelijk worden ingediend. Alle terugmeldingen op deze basisregistraties worden vervolgens centraal opgeslagen in het terugmeldsysteem (TMS) van het Kadaster en verder gedistribueerd naar bijvoorbeeld de bronhouder en PDOK. Zie ook het volgende filmpje: Terugmelden op de kaart – BAG, BGT, BRT - YouTube

Maar hoewel het al heel makkelijk is om een terugmelding te doen, zou het voor veel gebruikers nóg makkelijker zijn als ze direct vanuit hun eigen applicatie de terugmelding kunnen doen en bekijken. Daarom gaan we een terugmeld API opzetten waarmee terugmeldingen direct ingediend en uitgelezen kunnen worden. De API zal gefaseerd opgezet en uitgebreid worden:

In fase 1 zal de API alleen de GET methode ondersteunen: openbare informatie van terugmeldingen uit TMS kunnen daarmee worden opgehaald. Later zal het mogelijk worden om verschillende filterparameters op te geven.
In fase 2 zal de API ook de POST methode ondersteunen: terugmeldingen kunnen nu direct bij TMS worden ingediend.
In fase 3 wordt het mogelijk voor bronhouderapplicaties om alle informatie van terugmeldingen op te halen.
In fase 4 wordt het mogelijk voor bronhouderapplicaties om een statusupdate (PATCH) door te voeren.

We richten ons in dit topic vooral even op fase 1 en 2. Hierbij is nog niet alles uitgekristalliseerd maar kunnen we vast het volgende verklappen:

De Kadaster voorloop URL is nog even onbekend, maar de API zal benaderbaar zijn via /tms/v1/terugmeldingen
Via de API kunnen dus alle BAG, BGT en BRT terugmeldingen worden opgevraagd. Om alleen terugmeldingen van een specifieke registratie op te vragen, zal een filterparameter moeten worden opgegeven, bijv. GET terugmeldingen?registratie=BGT
Elke terugmelding krijgt een uniek nummer. GET terugmeldingen/1234 zal dus de melding met het nummer 1234 opvragen.
De API zal beveiligd zijn met een API key
De API key wordt uitgegeven na registratie via het (nog te publiceren) Kadaster developersportaal
Berichtuitwisseling is in GeoJSON (Point geometrie)
Coördinaatstelsel is RD
Voor de API volgen we grotendeels de richtlijnen zoals opgesteld door het DSO. Onder andere op het gebied van versionering: de major versie zal in de URI staan, in de header zal de major.minor.patch versie vermeld moeten worden.

We zijn nu hard aan het ontwikkelen zodat we begin 2018 de API kunnen publiceren met minimale functionaliteit. Uiteraard publiceren we niet dagelijks een API, dus alle tips, suggesties en vragen zijn altijd welkom! We zijn benieuwd naar jullie reactie!

dvh · 8 december 2017 om 15:10

Is het een idee om de OAS (OpenAPI Specification) op Github te delen zodat mensen daar suggesties kunnen doen?

JWSjoukema · 11 december 2017 om 15:27

Zeker een idee! Helaas zijn we op dit moment nog niet zover… Daarnaast horen we natuurlijk graag hoe jij dit aangepakt hebt met bijv. Ruimtelijke plannen

Ronald_Mulder · 24 mei 2018 om 07:13

@JWSjoukema kun je toelichten wat de huidige status is of waar ik dat kan nalezen?

Ik zou wel wat willen testen/ontwikkelen met de tms api. De url heb ik denk ik (https://api.kadaster.nl/tms/v1/terugmeldingen ?) maar er is ook een api key nodig. Als je wat info of documentatie hebt dan hou ik mij aanbevolen.

JWSjoukema · 24 mei 2018 om 08:09

Die URL heb je goed gevonden! Deze is inderdaad beveiligd met een API-key.

We hebben helaas dit jaar de terugmeld API ontwikkelingen voorlopig ‘on hold’ moeten zetten ivm het onverwachts ontbreken van budget hiervoor. Vandaar de lange radiostilte. Budgetaanvragen lopen bij de betrokken registraties en de eerste toezeggingen zijn er, waardoor we in ieder geval weer verder kunnen met ontwikkelen aan fase 1 en 2 (gedeeltelijk).

De planning is dat we in de zomermaanden hier weer verder aan werken en dan zullen we ook zeker API-keys aan geïnteresseerde partijen uitdelen voor testdoeleinden . We houden je op de hoogte!