URL's publieke REST services
Uitleg
REST (Representational State Transfer) is een stijl van software architecture voor het ontwerp van netwerk applicaties. Het fundamentele concept van een RESTful API is de 'resource'. Alle informatie die benoemd kan worden is een resource: een (gegenereerd) diagram, document, afbeelding, verzameling (collection) van resources, etc. In het geval van de BRO is dit bijvoorbeeld een Registratie Object. REST gebruikt een resource identifier om een resource te identificeren.
De status van een resource op een willekeurig moment heet een 'resource representation' en bevat data, metadata die de data omschrijft en hypermedia links die de gebruikers helpen het object te interpreteren.
Het data formaat van een 'resource representation' staat bekend als een 'media type' en stelt vast hoe de resource representation verwerkt moet worden.
Daarnaast zijn registratie-objecten gegroepeerd in registratiedomeinen. Dit is terug te vinden in de URL (/gm voor grondwatermonitoring, /sr voor bodem- en grondonderzoek). In de toekomst is de verwachting dat op domein niveau nieuwe functionaliteit wordt gerealiseerd.
Wat kun je met de REST services van de BRO?
De REST services zijn bedoeld voor machine-2-machine communicatie. Ze dienen als bouwblokken voor diensten die een gebruiker zelf kan maken. De diensten zijn met name bedoeld voor: opvragen van BRO-gegevens, visualisatie en validatie.
De uitgifte REST services zijn in principe bedoeld voor incidenteel gebruik. Voor uitgifte in bulk zijn ook Atom feeds beschikbaar. Om toch de stabiliteit van de dienstverlening te borgen en overvragen van de services te voorkomen is Rate Limiting geïmplementeerd. Hiermee wordt de toegang tot de diensten gelimiteerd en het aantal en de timing van de bevragingen onder controle gehouden. Dit om de BRO dienstverlening te garanderen en misbruik te voorkomen.
Indien de service wordt overvraagd verschijnt een melding dat het aantal verzoeken te hoog is (HTTP 429). Rate limiting is geïmplementeerd op de publieke REST services. Voor de BRO registratieobjecten zijn gemiddeld 5 requests per seconde toegestaan, specifiek voor de GLD endpoints gaat het om 3 requests per seconde.
Met de publieke REST services kan niet alle informatie worden opgevraagd die in de BRO beschikbaar is. In de gegevenscatalogi van de registratieobjecten is te vinden welke attributen alleen worden uitgeleverd aan de dataleverancier en de bronhouder. Via de SOAP uitgifte worden deze attributen wel uitgeleverd aan de dataleverancier en bronhouder.
Aanpassing URL's: in december 2021 hebben wij onze URL's aangepast zodat zij compliant zijn aan de REST Designrules van de NL overheid . De voormalige URL's (voorbeeldlink: https://publiek.broservices.nl/gm/gld-v1.0/) zijn in april 2022 uit productie genomen.
URL's
Hier onder staan de URL's van de beschikbare REST services. Met de weergegeven URL kom je in de productieomgeving terecht.
Voor de demo-omgeving of de acceptatie-omgeving kun je de bijbehorende REST services benaderen door toevoeging van 'int-' respectievelijk 'acc-' voor 'publiek'. Voorbeeld: https://int-publiek.broservices.nl/gm/gmw/v1/
Domein grondwatermonitoring
Uitgifte
- GMW uitgifte en validatie
url: https://publiek.broservices.nl/gm/gmw/v1 - GLD uitgifte en validatie
url: https://publiek.broservices.nl/gm/gld/v1
Experimenteel: haalt een GLD op op basis van een BRO-ID in CSV-format: zelfde URL: GLD uitgifte - GMN uitgifte en validatie
url: https://publiek.broservices.nl/gm/gmn/v1 - GAR uitgifte en validatie
url: https://publiek.broservices.nl/gm/gar/v1 - GM uitgifte
url: https://publiek.broservices.nl/gm/v1
uitgifte van grondwater in samenhang.- De relatie bezien vanuit de put (GMW) met de netwerken (GMN) waarin buizen van deze put deelnemen en de onderzoeken (GAR, GLD, FRD) die in de buizen van deze put zijn uitgevoerd
Visualisatie
- GMW Materiële geschiedenis (tijdlijn)
url: https://publiek.broservices.nl/gm/gmw/v1/material-history - GLD Visualisatie waterstanden
url: https://publiek.broservices.nl/gm/gld/v1/waterlevel
Domein bodem- en grondonderzoek
Uitgifte
- CPT uitgifte en validatie
url: https://publiek.broservices.nl/sr/cpt/v1 - BHR-P uitgifte en validatie
url: https://publiek.broservices.nl/sr/bhrp/v2 - BHR-GT uitgifte en validatie
url: https://publiek.broservices.nl/sr/bhrgt/v2 - BHR-G uitgifte en validatie
url: https://publiek.broservices.nl/sr/bhrg/v3 - SFR uitgifte en validatie
url: https://publiek.broservices.nl/sr/sfr/v2
Visualisatie
- Publieke visualisatieservice BHR-GT 2.1 boorprofielen
url: https://publiek.broservices.nl/sr/bhrgt/v2/profile - Publieke visualisatieservice CPT grafieken
url: https://publiek.broservices.nl/sr/cpt/v1/result - Publieke visualisatieservice BHR-G 3.0 boorprofielen
url: https://publiek.broservices.nl/sr/bhrg/v3/profile - Publieke visualisatieservice BHR-P 2.0 boorprofielen
url: https://publiek.broservices.nl/sr/bhrp/v2/profile - Publieke visualisatieservice SFR 2.0 wandprofielen
url: https://publiek.broservices.nl/sr/sfr/v2/profile
Domein grondwatergebruik
Uitgifte
- GUF uitgifte
url: https://publiek.broservices.nl/gu/guf/v1/ - GPD uitgifte
url: Grondwatermonitoringnet (GPD) (broservices.nl)
Uitgifte van grondwatergebruik in samenhang. Het grondwatergebruik domein (GU) omvat twee verschillende RO's die met elkaar geassocieerd zijn: GUF en GLD en waarvan alleen GUF een locatie heeft.
Domein Mijnbouwwet
Uitgifte
BRO algemene services
Waardelijsten
Het is mogelijk om een lijst met alle waarden (uit de catalogi) op te vragen bij de LV BRO via een REST-service.
Waardelijst Service
url: https://publiek.broservices.nl/bro/refcodes/v1
In de openAPI specificatie van de service zelf is een uitleg opgenomen, de zogeheten Swagger-uitleg.
Aanpassing URL refcodes: in december 2021 hebben wij onze URL's aangepast zodat zij compliant zijn aan de REST Designrules van de NL overheid . De voormalige URL (https://publiek.broservices.nl/refcodes/api/) is sinds april 2022 niet meer beschikbaar..