Digitale Delta API's

Dit is het eerste concept van de nieuwe Digitale Delta web site. Hij is nog in ontwikkeling (zowel qua inhoud als qua layout), en heeft in 2019 de oude website www.digitaldelta.nu vervangen.

This is the first draft for the new Digital Delta web site. Currently it is in Dutch only.
The API-specification however is in English.

 

DD-API 2.0

De Digitale Delta specificeert web service API's (Application Programming Interfaces) voor data-uitwisseling t.b.v. het waterbeheer. Deze API-specificaties zijn een open source product, waaraan door een groot aantal partijen wordt meegewerkt. Vanwege dit open source karakter zijn de specificaties op GitHub ondergebracht. De specificaties zijn opgesteld in RAML (zie raml.org voor de beschrijving van deze specificatietaal).

De meest geïmplementeerde en gebruikte Digitale Delta API is versie 2.0, kort gezegd DD-API 2.0. Hiermee kunnen tijdseries opgevraagd worden bij een databron, zowel metingen als modelresulten. Het gaat dan met name om waterkwantiteitsdata, zoals waterstanden, debieten, golfgegevens, regenmeters, et cetera. Waterkwantiteitsdata kenmerkt zich door een beperkte hoeveelheid metadata (samen te vatten tot grootheid, locatie, tijdspanne) en een grote hoeveelheid tijdstippen met waarden.

Bij de ontwikkeling van DD-API 2.0 is, ten opzichte van versie 1.0, gezorgd voor het beter aansluiten op standaarden, zoals GeoJSON en de API-strategie van de DSO. Daarnaast zijn er een aantal uitbreidingen geweest ten behoeve van:

Zie de pagina "Vertical profile and aspect specifications" voor een nadere beschrijving van laatstgenoemde twee punten.

De documentatie van de actuele versie van de DD-API (2.0.1) is te vinden in dd.v201.html.

Deze html-documentatie is gegenereerd uit de formele RAML-specificaties. De specificaties zijn opgesteld door de Digitale Delta technische werkgroep, en zijn een open source product @@@ staan in de dd-api repository op GitHub: https://github.com/DigitaleDeltaOrg/dd-api

Opmerking: de specificaties van DD-API 2.0 zijn compleet en afgerond. De documentatie is echter nog niet helemaal volledig. Er volgen nog extra beschrijvingen (met name voorbeelden van gebruik).

Gerelateerde API's

Naast bovengenoemde DD-API zijn de volgende API's beschikbaar:

In de volgende paragrafen worden deze gerelateerde API's kort langsgelopen.

DD-API 1.0

Deze eerste versie van de DD-API is eind 2016 gespecificeerd, en begin 2017 door een aantal partijen geïmplementeerd. Deze versie - zoals gezegd gericht op tijdseries - bevatte met enig kunst- en vliegwerk ook de ecologische data in dit tijdsreeksenformaat. Deze oplossing was echter verre van efficiënt voor het doelgebied van ecologische informatie: door een te beperkte toegang tot de veelheid van meta-data bleken de ecologische gegevens onvoldoende doorzoekbaar. Bij de uitbreiding van 1.0 naar 2.0 is daarom besloten om de ecologische data apart te behandelen (zie 'DD-ECO-API' hieronder).

De specificaties van DD-API-1.0 bevinden zich in de master-branch van de (ondertussen gearchiveerde want niet meer actieve) dd-api-spec repository op GitHub:
https://github.com/DigitaleDeltaOrg/dd-api-spec/tree/master. Uit de daarin aanwezige RAML-specificatie is een HTML-pagina gegenereerd met daarin de documentatie van DD-API 1.0.

DD-OPER

De DD-API is bedoeld voor het zoeken, vinden en opvragen van waterbeheergegevens. Een deel van de toepassingen ligt echter in het operationeel beheer van watersystemen, en bij dat operationeel beheer is het van belang dat de betrokken systemen en gebruikers slechts gegevens gebruiken die afgestempeld zijn als valide, en die te allen tijde beschikbaar zijn.
Om deze operationele systemen te voorzien van deze operationele data is door RWS een speciale set afgebakende opvraagmogelijkheden gedefinieerd. Deze operationele variant van de DD-API is DD-OPER genoemd, en is niets anders dan een andere syntax voor het bevragen van de databronnen, waarbij het 'vrij doorzoeken' niet mogelijk is. De reponse van de DD-OPER is identiek aan die van de DD-API, maar bevat minder velden: het deel van de meta-data dat voor het vrij doorzoeken van belang is wordt weggelaten.

De documentatie van de actuele versie van de DD-OPER (versie 2.0.1, deze is altijd gelijk aan die van de DD-API) is te vinden in dd-oper.v201.html.

Deze html-documentatie is gegenereerd uit de formele RAML-specificaties. Deze zijn opgesteld door RWS, in samenwerking met de Digitale Delta technische werkgroep, en vormen onderdeel van de dd-api repository op GitHub: https://github.com/DigitaleDeltaOrg/dd-api

DD-ECO-API 1.0, voor ecologische data

Ecologische data betreft metingen die betrekking hebben op organismen en op de wisselwerking tussen organismen: levensgemeenschappen in en rond het water. Dit betekent dat naast de organismen chemische en fysische kenmerken ontsloten worden. Onder chemische kenmerken worden alle chemische stoffen en samenstellingen gerekend, bijvoorbeeld chloor, zware metalen, (gewassen-)bestrijdingsmiddelen en medicijnen. Onder fysische kenmerken vallen bijvoorbeeld troebelheid, diepte, stroming, zuurgraad, temperatuur, oeverbegroeiing, etc. Ecologische data kenmerkt zich een beperkte hoeveelheid data, vaak slechts één gemeten waarde, en uitvoerige meta-data om de meting te beschrijven.

De DD-ECO-API is gesplitst in twee onderdelen: het measurements-deel voor het gericht opvragen van metingen, en het discovery-deel voor het uitgebreid doorzoeken van beschikbare ecologische data.
Voor beide delen zijn uit de RAML-specificaties HTML-pagina's gegenereerd:

De RAML-specificaties van de DD-ECO-API zijn te vinden in master-branch van de dd-eco-api-specs repository op GitHub:
https://github.com/DigitaleDeltaOrg/dd-eco-api-specs