Omgevingsdocumenten presenteren: tekststructuur van regelingen niet beschikbaar in html

Organisaties Digitaal Stelsel Omgevingswet
, , ,
#1

Hoi,

Ik probeer de teksten behorend bij een omgevingsdocument te presenteren op een webpagina. Daarvoor gebruik ik de omgevingsdocumenten presenteren API. Standaard komen de teksten terug in xml formaat.

In de documentatie (gelinkt via Omgevingsdocument presenteren - Ontwikkelaarsportaal) staat dat op het GET regelingen/:id/tekststructuur endpoint, de volgende header gebruikt kan worden om de teksten in html te ontvangen:
‘Content-Type-Embedded’: ‘text/html’

Deze header lijkt echter geen effect te hebben. Heeft iemand ervaring met dit endpoint of het opvragen van de teksten in html?

Fijne dag,
Blue

#2

Ik bleek met GET regelingen/:id/tekststructuur het verkeerde endpoint te hebben. De juiste is: GET regelingen/:id/documentcomponenten. Dezelfde url is ook te vinden vanuit een regeling onder: regeling._links.documentstructuur.href.

De header werkt wel voor documentcomponenten. Dat was me niet duidelijk uit de documentatie, maar ik ben erg blij dat de feature wel bestaat!

1 like
#3

De OpenAPI Specificatie (OAS) op het ontwikkelaarsportaal is te kopiëren naar editor.swagger.io. Daarmee krijg je daar een visuele weergave van de OAS.

Ik wil je er wel nog op wijzen dat de mogelijkheid tot het opvragen van teksten in HTML formaat inderdaad alleen op het deprecated /regelingen/{identificatie}/documentcomponenten endpoint bestaat. Dit endpoint is vervangen door het /regelingen/{identificatie}/tekststructuur endpoint in dezelfde API die niet de mogelijkheid voor teksten in HTML meer biedt (zoals je zelf al had gemerkt).

De deprecation van het endpoint geeft aan dat we dit endpoint in een volgende versie van de API niet terug zullen laten komen.

#4

Dank voor je toelichting.

Naar het /regelingen/{identificatie}/documentcomponenten endpoint wordt nog wel verwezen vanuit het ‘regeling’-object: regeling._links.documentstructuur.href (althans, in de preproductieomgeving).
Zie bijvoorbeeld de response van: https://service.pre.omgevingswet.overheid.nl/publiek/omgevingsdocumenten/api/presenteren/v7/regelingen/_akn_nl_act_gm0344_2020_omgevingsplan?geldigOp=2023-11-15&inWerkingOp=2023-11-15&beschikbaarOp=2023-11-15T06:46:03Z

Weet je misschien of die verwijzing ge-update zal worden naar /regelingen/{identificatie}/documentcomponenten/{componentWorkId}? Dat endpoint zou niet deprecated moeten zijn volgens de documentatie.

Of: enig idee of het op de planning staat om /tekststructuur ook als html opvraagbaar te maken?

#5

Vanwege backwards compatibility zijn verwijzingen naar het deprecated endpoint niet uit de respons geschrapt.

Die verwijzing zal niet aangepast worden naar /regelingen/{identificatie}/documentcomponenten/{componentWorkId} , want daarmee haal je slecht één documentcomponent op ipv de volledige set.

En, nee, het staat niet op de planning om HTML output op het /tekststructuur endpoint beschikbaar te maken.

#6

Nogmaals dank voor je reactie, Robin.

Mag ik vragen waarom het niet op de planning staat om de html output beschikbaar te maken op het nieuwe endpoint?

Het lijkt me straightforward genoeg om een xml-html parser te vinden of schrijven voor de /tekststructuur output. Toch ben ik benieuwd of jullie hier zelf een standaardmanier voor hebben. Weet jij dat of heb je andere tips?

Ten slotte: enig idee wanneer de ondersteuning voor het deprecated endpoint definitief wordt beëindigd?

#7

De brondata is XML, en we proberen zo min mogelijk afgeleide data uit te leveren. En dan is dit nog een speciaal geval omdat er meerdere mogelijke transformaties tussen de bron XML en HTML mogelijk zijn. Welke moeten we kiezen zodat iedere gebruiker er mee uit de voeten kan en tevreden is?

De volledige Presenteren V7 API gaat een half jaar na het uitbrengen van de Presenteren V8 API uit de lucht. Planning staat nog niet vast, maar de V8 zou in de eerste helft van volgend jaar beschikbaar moeten komen.

2 likes
#8

Dit snap ik niet goed. In mijn beleving is de presenteren API juist grotendeels gevuld met afgeleide data. Juist de opvragen API waar de uitgeleverde data veel meer lijkt op de aangeleverde objecten (in mijn beleving dus minder afgeleid is) is uitgefaseerd. Graag zie ik ook geometrie in een WKT of gml formaat ipv vector tiles (da’s in mijn beleving ook afgeleide data).

Ik zit dus juist te springen om een API waarin ik de door mij uitgeleverde objecten kan herkennen en waarin ik kan zien of mijn objectenadministratie overeenkomt met die van OZON. Of zie ik hier iets over het hoofd?

Een toelichting (eventeel in een apart topic) wordt buitengewoon op prijs gesteld.

1 like
#9

Voor dit soort feature requests kan je het beste contact opnemen met het IPLO. Die zorgen dat het op de juiste plek terecht komt voor beoordeling en mogelijke uitvoering.