Catalogus opvragen (REST API) - Feedback

Laat hier je feedback op de API Catalogus opvragen achter.

De stelselcatalogus voor de Omgevingswet verbindt definities, toelichtingen en uitleg van begrippen, regels, informatiemodellen, producten en services met elkaar. Met deze API kunnen begrippen worden opgevraagd. Van ieder begrip geeft de API de formele definitie, uitleg in klare taal, bron en gerelateerde begrippen.

De API Catalogus Opvragen vind je in het API-register.

Vol verwachting mijn verse API-key geprobeerd op deze service via Postman, krijg ik een http 202 terug: dit betekent zoiets als: “ja, ik begrijp wat je bedoelt maar ik geef lekker niks terug”.
http 202 staat overigens niet beschreven in de API strategie dd 12 maart 2018.
Kijken jullie nog even naar de implementatie?

Dank voor je feedback Rob!

Rob, kun je de URL van de request die de 202 gaf doorgeven?

Ik heb net enkele requests gedaan (op bijv. https://service.pre.omgevingswet.overheid.nl/publiek/catalogus/api/opvragen/v1/concepten) en krijg normaal antwoord (met http 200). Oftewel, ik kan het nog niet reproduceren.

Hoi Bob, ik kreeg de 202 op https://service.pre.omgevingswet.overheid.nl/publiek/catalogus/api/opvragen/v1 ; met /concepten erachter krijg ik idd de lijst met concepten.

Misschien de geldige opties teruggeven op https://service.pre.omgevingswet.overheid.nl/publiek/catalogus/api/opvragen/v1 ? Een prettig principe van REST is autodiscovery / follow your nose…

Een http 202 is zo’n beetje het meest frustrerende antwoord dat je kunt krijgen: om even in de sfeer van deze warme zonnige middag te blijven: alsof je tegen de ijscoman zegt “Goedemiddag, graag zo’n heerlijke softijs met slagroom” en het antwoord is “Goedemiddag” (en er volgt geen ijs, zonder opgaaf van reden).

Klopt het dat er geen data in de API zit?

Ik heb verschillende calls geprobeerd, maar ik krijg altijd een lege array terug. ([]).

De vraag is uitgezet!

Ik heb inmiddels antwoord gehad, er zat inderdaad nog geen data in en die wordt vandaag waarschijnlijk ingevoerd.

Dat is goed nieuws!

De data is inmiddels in de omgeving geladen en de API is daarmee weer volledig functioneel.

Hallo. Er lijkt iets mis te zijn met de JSON-file van de API-definitie voor de stelselactalogus. Ik krijg bij het inlezen van de API-definitie in ReadyAPI deze melding:
attribute paths.’/concepten’(get).parameters. There are duplicate parameters values

Hallo @ArnoldHenselmans ,

Bedankt voor de melding. Het blijkt een fout te zijn in onze API-definitie.
Wij gaan dit zo snel mogelijk aanpassen zodat het inlezen weer goed gaat.

Met vriendelijke groeten,

Antek Drzewiecki

Goedemiddag @ArnoldHenselmans,

We hebben de API aangepast en daarmee het probleem verholpen.
Inmiddels is deze nieuwe API specificatie beschikbaar.

Met vriendelijke groet,
Jurjen Andries.

hmm, op https://service.pre.omgevingswet.overheid.nl/publiek/catalogus/api/opvragen/v2/concepten krijg ik een volledige lijst.

Als ik probeer specifieker te zijn middels een query, bijvoorbeeld

Dit soort URL’s leveren fouten pagina’s op:

Het is mij niet gelukt om ook maar een van de geprobeerde voorbeelden uit de documentatie op ReDoc Interactive Demo

aan de praat te krijgen.

Graag zie ik een voorbeeld van een werkend request.

Hallo Marco, ik heb het team gevraagd naar je vragen te kijken en waar nodig ook de API specificatie te updaten (ik vermoed dat er wat oude voorbeelden in zitten en dat op een aantal plekken er generieke voorbeelden worden gebruikt in plaats van specifieke).

Een request dat bij mij werkt is:
https://service.pre.omgevingswet.overheid.nl/publiek/catalogus/api/opvragen/v2/concepten?term=afval, ik krijg dan 1 specifiek concept terug.

Dat de URL:
https://service.pre.omgevingswet.overheid.nl/publiek/catalogus/api/opvragen/v2/collecties/?term=afval een foutmelding oplevert is correct, de “/” na “collecties” hoort daar namelijk niet.

Een ander werkend request (om alle waardes in een waardelijst op te halen is):

https://service.pre.omgevingswet.overheid.nl/publiek/catalogus/api/opvragen/v2/waardesInWaardelijst?waardelijst=http://standaarden.omgevingswet.overheid.nl/id/waardelijst/Activiteitengroep_1.0.3

Jasper,

Dank voor je antwoord. En inderdaad, deze werkt: https://service.pre.omgevingswet.overheid.nl/publiek/catalogus/api/opvragen/v2/concepten?term=afval

Ikzelf probeerde eerde deze, en die werkt NIET: https://service.pre.omgevingswet.overheid.nl/publiek/catalogus/api/opvragen/v2/concepten?term=Aankleding

Maar deze werkt WEL: https://service.pre.omgevingswet.overheid.nl/publiek/catalogus/api/opvragen/v2/concepten?term=aankleding

En dat laatste is raar, want de term is “Aankleding” en niet “aankleding”.

Is dit inderdaad hoe de API zich hoort te gedragen? En zo ja, kun je me verwijzen naar documentatie waarin dit gedrag beschreven staat?

Verder doe ik de suggestie om in lijn met de OZON API’s ook een _self (ofzo) eigenschap op te nemen met URL die verwijst naar het object zelf. Dit maakt een API erg zelf-uitleggend.

En aanvulling op mijn bovenstaande commentaar:

De volgende 3 URLS werken geen van allen:

Hoe dien ik te zoeken op deze term?

Dank voor je feedback en suggesties, we komen hier begin volgende week op terug.

Hoi Marco,

Dank voor je bevindingen.
Ik zal de voorbeelden in de documentatie bij laten werken, dat is inderdaad niet netjes. Waarschijnlijk is dat het resultaat van een migratie welke wij dit voorjaar hebben gedaan.

Het begrip Aaneengesloten Bodemvoorziening kun je met de volgende call vinden:
https://service.omgevingswet.overheid.nl/publiek/catalogus/api/opvragen/v2/concepten?term=aaneengesloten%20bodemvoorziening
Term in de APi zoekt op het RDFS label van het begrip zoals dat achter label staat in de frontend.

We zijn momenteel bezig met het opstellen van een V3 van de API waarin we dergelijke zaken gaan verbeteren. Hierin zullen ook andere zaken opgepakt worden om tenminste aan de API-strategie van de DSO te voldoen.

Met vriendelijke groet,

Finn Tiebout.

Finn,

dank. Helaas is deze zin voor mij nogal onbegrijpelijk:

Ik denk dat je bedoeld dat ik de waarde achter “label” in de frontend moet gebruiken om te zoeken op “term” in de API.

Maar dat is toch raar? Het idee is toch dat je in een API een term kunt vinden op de waarde van een tem ipv op de waarde van het label?

Ik zou dit wel logisch vinden:

https://service.omgevingswet.overheid.nl/publiek/catalogus/api/opvragen/v2/concepten?label=aaneengesloten%20bodemvoorziening

of

https://service.omgevingswet.overheid.nl/publiek/catalogus/api/opvragen/v2/concepten?naam=aaneengesloten%20bodemvoorziening

Wat mis ik hier in de logica?