Developer experience API's op geo basisgegevens

Toepassingen PDOK Website en Viewer
#1

DOEL: Wat vinden developers een goede experience als ze werken met API’s op geo basisgegevens van de overheid.

Beste PDOK

in het kader van doorontwikkelen in samenhang zou het fijn zijn de developer experience bij het werken met geo basisgegevens makkelijk en goed aan te bieden. Er wordt daarom op de PDOK website met de Open API Specifictatie OAS3 gewerkt, die developers met tooling ondersteunt snel, makkelijk en goed applicaties te ontwikkelen.

In dat kader:

de developer experience van de API beschrijving van de TMS terugmeldingen-API kan nóg beter…

als ik op

https://www.pdok.nl/restful-api/-/article/terugmeldingen-1#

navigeer, dan mis ik een introductietekst die me helpt begrijpen wat ik kan met deze API, en inzichtelijk maakt wat de opbouw is van de beschrijving.

Bovendien reageert de website in Chrome wat schokkerig, en met name het uitklap-scherm aan de linkerkant biedt wisselende functionaliteit.

Als ik op (ter vergelijking) op

https://www.pdok.nl/restful-api/-/article/basisregistratie-adressen-en-gebouwen-ba-1#

navigeer vind ik de introductietekst makkelijker te begrijpen. De website reageert ook hier wat schokkerig.

De API beschrijving van de DKK op

https://downloads.pdok.nl/kadastralekaart/api/v4_0/ui/

geeft me een andere developer experience dan de voorgaande, hoewel ze ook gaat over geo basisregistraties.

Nog een ander voorbeeld vind ik op

https://www.bronhouderportaal-bro.nl/doc/api.html

waar een officiële styling van de overheid is gebruikt.

#2

Het is idd wel wat uitzoekwerk om alle API’s te kunnen doorgronden. Dat er verschillen zijn vind ik niet heel erg, zo is de API van de DKK afwijkend omdat de hele structuur anders is dan een WFS bijvoorbeeld.

Ik heb wel het idee dat het steeds beter vindbaar is en dat er beter wordt gedocumenteerd dan pakweg 2, 3 jaar geleden. Toch kan de documentatie wel wat uitgebreider. Hier op het forum worden soms allerlei aanvullingen geplaatst of uit discussies volgt extra informatie die prima bij de API documentatie gevoegd kan worden. Bijvoorbeeld bij de DKK wordt niet beschreven hoelang een download beschikbaar blijft en staat ook niet of er een grootte-beperking is voor de polygoon of het gebied. En ik mis een voorbeeld van een multi-polygoon zodat ik dat ergens anders moet gaan uitzoeken (zomaar wat voorbeelden :slight_smile: )

Wat ik persoonlijk lastig vind zijn de volgende punten (mijn developer experience):

  • spontane wijzigingen in de datamodellen of ineens andere datumnotaties, die niet gecommuniceerd worden, niet bij een versie horen en soms na enige tijd weer hersteld worden
  • verschil in aangeboden formaten, wel/geen XML of JSON, verschil in WMTS/WFS versies
  • ontbrekende projecties van WMTS bronnen
  • aangeboden services die ineens weer verdwijnen (b.v. WFS van BRO die weer komen te vervallen)
  • vindbaarheid van de documentatie van de datamodellen of schema’s (PDOK, NGR, Geonovum, GitHub), overal vind je wel ergens een PDF of een pagina met wat informatie maar nooit zeker of het de laatste versie is en of je wel alles hebt (aanvullende Excel-bestanden bijvoorbeeld)

Maar over het algemeen ben ik erg blij met alles wat via PDOK/NGR wordt aangeboden en dat er gemakkelijk te communiceren is met de personen die betrokken zijn bij de services. Ik merk ook dat buitenlandse contacten erg jaloers zijn op wat er in Nederland allemaal kosteloos beschikbaar is.

1 like