BAG REST API documentatie op PDOK-website onvolledig en onoverzichtelijk

Als ik de BAG REST API documentatie op de PDOK website bekijk, ontbreekt er volgens mij een (vrij essentieel) stukje.

Het gaat bijvoorbeeld bij ‘Geografisch zoeken op één of meer instanties van een pand’ om deze tekst:

De lengte- en breedtegraad in WGS84, EPSG:4326. Deze is nagenoeg gelijk aan ETRS89 EPSG:4258 en kan als standaard lengte- en breedtegraden worden gebruikt.

Als ik de link naar het YAML-document kopieer en deze open in de Swagger-editor, zie ik deze tekst wel terug.

Meer in het algemeen vind ik de documentatie zoals die in de standaard Swagger UI wordt weergegeven overzichtelijker dan die op de PDOK-website. Als je bijvoorbeeld meer wilt weten over dieperliggende key-value pairs in het request body schema bij filteren op geometrie, moet je op het groter dan (>) of punt (.) teken klikken (rood omlijnd in de schermafdruk). Dat was mij niet meteen duidelijk.

@FrieseWoudloper bedankt voor je feedback! We gaan er naar kijken.

Laat ik om te beginnen zeggen dat ik bijna plaatsvervangend trots ben dat het Kadaster zo veel informatie openbaar beschikbaar stelt en ons yaml-files geeft met de noodzakelijke informatie. Top dat FrieseWoudloper dit extraatje vraagt. Zelf heb ik ook nog een wens: meer voorbeelden per endpoint van de opbouw van de request body. Zoals bij api/v1/woonplaatsen. Daar krijg ik alleen een 504, wat ik ook probeer. Wellicht iets voor jullie om ook mee te nemen.

@TimvanSteenbergen nemen we ook mee! Bedankt :+1:

Klopt, dit is een bug in ReDoc. Wanneer dit verholpen wordt weet ik niet, maar wij kunnen het eenvoudig oplossen door deze omschrijving een niveautje hoger te herhalen, gaan we fixen!

Dat is een kwestie van smaak. Steeds meer API aanbieders stappen over naar alternatieve representaties zoals ReDoc, mede vanwege het zogenaamde ‘three-panel-design’: navigatie - operaties - voorbeelden. SwaggerUI is slechts een simpele tool om even snel de OpenAPI Specificatie te kunnen visualiseren (zijn overigens hun eigen woorden), alternatieven trachten meer aandacht te besteden aan de UX (responsive, toegankelijk, meer voorbeelden, etc.) en zodoende meer richting ‘documentatie’ ipv ‘visualisatie’ te verschuiven.

Het is overigens wel zo dat er nog een bug open staat m.b.t. de styling, waardoor ReDoc er niet helemaal goed uitkomt. Via http://rebilly.github.io/ReDoc/?url=https://rawgit.com/PDOK/open-api-specs/master/bag/oas.v1.yaml kun je zien hoe het er eigenlijk uit hoort te zien. Mooie hier is natuurlijk dat de spec zelf ook gepubliceerd is, zodat iedereen in principe zijn/haar eigen voorkeurstool kan gebruiken :wink:

Dankjewel voor de informatie @dvh. Erg interessant! En misschien heb je wel gelijk wat de styling van Swagger UI betreft. Misschien moet ik gewoon even wennen :wink:

@dvh: Toch nog een vraagje naar aanleiding van bovenstaande thread. In het algemeen, als je zo flexibel mogelijk wilt zijn ten aanzien van API documentatie, maakt het dan uit of de documentatie in YAML of JSON is? Welk formaat heeft de voorkeur als je verschillende opties wilt ondersteunen voor het visualiseren van de documentatie en het automatisch genereren van code?

YAML en JSON zijn volledig 1:1 converteerbaar dus de een doet niet onder voor de andere. JSON is beter te begrijpen voor machines (vandaar dat de meeste tools die ook YAML ondersteunen eerst de boel converteren naar JSON voor intern gebruik), YAML is beter leesbaar en ‘schrijfbaar’ voor mensen.

1 like