Op dit moment wordt er hard gewerkt aan de ontwikkeling van de Terugmelding Bronhouder API. Deze API is een aanvulling op de al bestaande Terugmelding API, waarmee gebruikers al terugmeldingen kunnen doen en lezen vanuit een externe applicatie.
De nieuwe Terugmelding Bronhouder API maakt het mogelijk voor bronhouders om vanuit een eigen applicatie terugmeldingen in te lezen en te wijzigen (bijvoorbeeld van status). Bij het inlezen kunnen ook de gevoeligere velden van een terugmelding zoals e-mailadres en bijlagen bekeken worden. Vandaar dat een bronhouder alleen de terugmeldingen kan zien die aan diegene zijn toegewezen en de API beveiligd wordt via Oauth.
Net als de Terugmelding API werkt deze API generiek voor o.a. de BAG, BGT en BRT.
Binnenkort (verwachting: oktober) zullen we de documentatie en de acceptatietestomgeving beschikbaar maken. Heb je interesse om actief mee te testen? Stuur dan een mailtje naar terugmeldingapi@kadaster.nl
Eind dit jaar zal de API naar verwachting in productie worden genomen.
In de API beschrijving 1.1.2 zie ik dat meldingen kunnen opgevraagd op basis van hun status. Wat ik niet terugvind is een mogelijkheid om vervolgens deze status te kunnen updaten zodat de meldingen kunnen worden afgemeld.
Er wordt nog gewerkt aan een website waarin u de specificatie visueel kan bekijken inclusief aanvullende uitleg en een aanmeldformulier. Voorlopig kunt u deze specificatie alvast bekijken in uw eigen tool of bijvoorbeeld via Swagger UI.
Heeft u vragen? Laat dit weten via e-mail op terugmeldingapi@kadaster.nl
De nieuwe versie 1.0.1 van de Terugmelding bronhouder API is nu actief op de acceptatie omgeving. Er is een kleine wijziging doorgevoerd bij het doorsturen van een terugmelding naar een andere registratie, zie verder de change log in de Terugmelding bronhouder API OAS3.
Heeft u interesse om deel te nemen in het test traject met uw eigen applicatie? U kunt uw applicatie nu registreren via Aanvragen oAuth. U dient dan te kiezen voor de âAcceptatieomgevingâ.
Wat is het nut van de status Doorgestuurd? Eenmaal doorgestuurd naar een andere bronhouder zie ik deze melding niet meer. En het lijkt me dat de melding voor de andere bronhouder de status NIeuw moet hebben?
In de api-doc worden de volgende statussen genoemd:
NIEUW,IN_ONDERZOEK,GOEDGEKEURD,GEPARKEERD,DOORGESTUURD,AFGEWEZEN,AFGEROND
In de gebruikers interface worden de volgende statussen getoond:
Nieuw, In onderzoek, Goedgekeurd, Doorgestuurd, Afgewezen, Afgerond, Spam
Conclusie: GEPARKEERD = Spam ?
Doorsturen is niet wat je er van zou verwachten. Het is eigenlijk kopieren. Had verwacht dat een eenmaal doorgestuurde melding niet meer beschikbaar is voor de betreffende registratie, maar dat is niet zo. Er wordt een kopie gemaakt en vervolgens kan je er gewoon weer mee doorwerken.
Het zou handig zijn als in de API documentatie ook de 412 responses worden beschreven.
Bijvoorbeeld bij een PATCH request waarin de statusCode van een melding op GOEDGEKEURD wordt gezet krijg ik een http 412 met als content: reden: Aangeboden wijziging is al verwerkt. (wat is het nut hiervan?)
Zijn er nog andere waarmee ik rekening moet houden?
Goed punt: in de documentatie ontbreekt de status Spam. Dit is wel een andere status dan de status Geparkeerd.
Geparkeerd is een extra status voor alleen de BRT om aan te geven dat de terugmelding niet verder onderzocht kan worden totdat nieuw bronmateriaal (luchtfoto) beschikbaar is.
Spam is een status die er voor zorgt dat de terugmelding direct verwijderd wordt. Vandaar dat je deze status niet kan âGET-enâ, maar wel PATCH-en. We gaan dit in de beschrijving toevoegen.
Bij een doorgestuurde melding wordt er automatisch een nieuwe terugmelding aangemaakt voor de andere registratie waar het naar toegestuurd is. âDoorgestuurd naar andere basisregistratieâ is net als âafgerondâ en âafgewezenâ een eindstatus: deze blijven een tijdje zichtbaar zodat de terugmelder kan zien wat er mee gebeurd is, maar verdwijnen dan. Technisch wordt inderdaad niet afgdwongen dat een eindstatus niet meer gewijzigd mag worden.
In de werkwijze die wij willen gaan hanteren worden alle nieuwe meldingen beoordeeld in de online beheerapplicatie bij kadaster. Meldingen die we gaan oppakken krijgen de status goedgekeurd. Goedgekeurde meldingen worden opgepakt door onze software via de API en krijgen uiteindelijk de status Afgehandeld.
Wat ik mis in de online beheerapplicatie is een filter op status zodat je snel een overzicht kan krijgen van bijvoorbeeld alleen de nieuwe meldingen.
In de beheerapplicatie zitten blijkbaar al wat gedachten over hoe ik hiermee moet omgaan. Zo mag ik een status niet terug op Nieuw zetten. Waarom niet ? Wat voor beperkingen zitten er allemaal in?
De registratie waar een melding voor wordt aangemaakt is afhankelijk van het zoomniveau? Gaat de gemiddelde gebruiker dat begrijpen. Waarom niet expliciet aangeven voor welke registratie het is?
Filterfunctionaliteit op status zal toegevoegd worden aan de beheerapplicatie en beschikbaar zijn bij livegang.
De API dwingt inderdaad nu technisch geen bepaalde status flow af. Betekent natuurlijk niet dat er geen logische flow is. Een bronhouder is wettelijk verplicht om een terugmelding binnen enkele werkdagen in onderzoek te nemen. Status âNieuwâ impliceert dat de bronhouder nog niet naar de terugmelding gekeken heeft. Het is daarom niet logisch dat een bronhouder een terugmelding van bijvoorbeeld âin onderzoekâ naar ânieuwâ zet en daarom hebben we dit ook niet mogelijk gemaakt in de beheerapplicatie.
Ik gok dat je het hier hebt over Verbeter de Kaart? Via de API moet je expliciet aangeven voor welke registratie je meldt. Bij Verbeter de Kaart wordt die voor de gebruiker als service voor je ingevuld, afhankelijk van op welke kaart je meldt. Juist met het idee dat een gemiddelde gebruiker niet hoeft te weten of ie op de BRT of BGT meldt (en wat een BGT of BRT precies is): je ziet iets op de kaart wat niet klopt en je meldt het direct om dat te verbeteren. En ja, dat werkt al meer dan vijf jaar prima
Vandaag is versie 1.0.2 van de Terugmelding bronhouder API verschenen. In deze versie is header veld API-Version voortaan niet meer nodig, zie verder de change log bij PDOK.
Verder is de documentatie bijgewerkt: een kleine wijziging in de instructies en er is extra toelichting opgenomen bij de PATCH voorbeelden in de OAS3 inclusief een uitleg van de statusCode SPAM. Tenslotte is de response HTTP 412 nu beschreven bij een PATCH.
Update: de extra toelichting bij de PATCH voorbeelden is door technische redenen helaas (nog) niet te zien op de PDOK site. Dit is wel te zien door de OAS3 te bekijken met uw eigen tool of Swagger UI.
Vandaag is versie 1.0.3 van de Terugmelding bronhouder API verschenen. In deze versie wordt bij een niet verwerkbaar bericht bij een PATCH voortaan een andere statuscode terug gegeven namelijk 422 Unprocessable Entity.
De acceptietest voor de Terugmelding bronhouder API is succesvol afgesloten. Hartelijk dank voor de input!
Bij deze kunnen we aankondigen dat de Terugmelding bronhouder API op 15 februari in productie zal gaan.
Indien u nog input en/of bevindingen heeft voor de Terugmelding bronhouder API, dan kunt u die uiteraard blijven geven via dit forum of het eerder aangegeven e-mail adres.
