HydroDaten API Standard
for Developers

Guideline

Diese Handreichung zum HydroDaten API Standard (HyDAS) ist eine vertiefende Ergänzung zu den bereitgestellten Informationen in der Einführung.

Der Standard ist in zwei Varianten verfügbar:
BASIS (Basisversion mit 3 Endpunkten als Grundlage) und ERWEITERT (Komplettversion mit allen Endpunkten und Features).
Diese Guideline gilt für beide Varianten. Features, die nur in der erweiterten Variante verfügbar sind, sind entsprechend gekennzeichnet.

Inhalt

Vorüberlegungen bei Implementation des Standards

Im Wesentlichen muss festgelegt werden, wie bestehende Datenstrukturen auf den HydroDaten API Standard abgebildet werden können. Dabei gilt es zu bestimmen, welche Teile des Standards umsetzbar sind und welche eventuell nicht realisiert werden können. Als Grundlage kann die Basisversion des Standards mit Ergänzungen aus der erweiterten Version dienen.

An einigen Stellen kann es erforderlich sein, über diesen Standard hinauszugehen und zusätzliche Attribute sowie Abfragen zu definieren. In solchen Fällen sollte die vorliegende Open API Spezifikation des Standards erweitert und entsprechend angepasst werden. Die Spezifikation kann dann in ihrer modifizierten Form verwendet werden, um Server-, Client- oder Dokumentationsartefakte zu generieren (siehe folgende Abschnitte und auch Vorgehen für eine Implementation des HyDAS).

Die Datentypen des HyDAS können auch zur schema-konformen Erstellung reiner Datendateien genutzt werden. Diese können im Datenaustausch zwischen Systemen verwendet oder zum Download angeboten werden. Es handelt sich dann nicht mehr um eine API im engeren Sinne.

Wichtige Hinweise zur Spezifikation

Zeitangaben

Zeitstempel, also minuten- oder sekundengenaue Zeitangaben entsprechen dem internationalen ISO Standard 8601. Dieser Standard bietet den Usern im Vergleich zu einem UNIX-Timestamp eine bessere Lesbarkeit. Die Zeitangaben in diesem Format sollten mit einem Zeitzonenoffset (+1) versehen sein, damit die Zeitangabe eindeutig interpretierbar ist.

Beispiel: 2025-01-27T12:00:00+01:00

Hinweis zur Koordinatenumwandlung nach WGS84

Idealerweise werden alle Punkt-Koordinaten in WGS84 in der API publiziert. WGS84 ist das weltweit am häufigsten genutzte System zur Positionsbestimmung insbesondere für das GPS-Systems.

Es mag daher notwendig sein, eine Koordinatentransformation nach WGS84 durchzuführen. Hier kann es zu Ungenauigkeiten kommen. Daher müssen die Transformations-Regeln für Deutschland präzisiert werden. Dazu kann für die häufig verwendeten Gauß-Krüger Koordinatenreferenzsysteme (EPSG 31461-31469) folgende Transformationsregel konfiguriert werden (7-Parameter Helmert Transformation): TOWGS84[598.1,73.7,418.2,0.202,0.045,-2.455,6.7]. Der Fehlerbereich liegt hier zwischen 0,5 und 1,5 Metern.

Für eine noch genauere Transformation mit einem deutlich kleinerem Fehlerbereich eignet sich die NTv2 (BeTA2007) Transformation.

Versionierung

Bei der Weiterentwicklung einer API sollte auf Abwärtskompatibilität geachtet werden. Das bedeutet, dass bestehende Clients auch eine sich verändernde Schnittstelle weiter nutzen können sollten. Ist dies nicht möglich, muss eine neue API-Version bereitgestellt werden, während die alte Version für einen definierten Zeitraum parallel verfügbar bleibt.

URL-Versionierung (empfohlene Methode)

Die empfohlene Vorgehensweise für eine HydroDaten API ist die Versionierung über die URL (Path-based Versioning). Die Versionsnummer wird dabei als Pfad-Segment in die URL integriert (z.B. /v1/, /v2/).

Beispiel:

https://api.hvz.baden-wuerttemberg.de/v1/stations
https://api.hvz.baden-wuerttemberg.de/v2/stations

Implementierung:

Breaking vs. Non-Breaking Changes

Nicht jede Änderung an der API erfordert eine neue Major-Version. Es ist wichtig, zwischen breaking und non-breaking Changes zu unterscheiden.

Breaking Changes (erfordern neue Major-Version)

Breaking Changes machen eine neue Major-Version erforderlich (z.B. v1 → v2):

Non-Breaking Changes (können in bestehender Version deployt werden)

Diese Änderungen sind abwärtskompatibel und erfordern keine neue Major-Version:

Metasektion

Eine Metasektion in der API ist sinnvoll, weil sie wichtige Informationen über die API bereitstellt, wie Titel, Version und Lizenz, die für Entwickler und Nutzer entscheidend sind, um die API korrekt zu nutzen und zu integrieren. Darüber hinaus fördert die Metasektion die Transparenz und Nachvollziehbarkeit, indem sie klare Kontaktinformationen und Dokumentationslinks bietet, die den Zugriff auf weitere Ressourcen erleichtern.

Der Response der API enthält an oberster Stelle eine Metasektion, welche u. a. die zuvor beschriebenen Informationen enthält. Beispielhaft die Metasektion der Ressource stations als JSON:

"meta": {
    "title": "Projekt HydroDaten API",
    "version": "1.0.0",
    "description": "API für hydrologische Stationsdaten, Mess- und Kennwerte",
    "descriptionUrl": "https://dev.hochwasserzentralen.de/hydrodaten-api/",
    "baseUrl": "https://api.example.io/v1",
    "publisherName": "Hochwasservorhersagezentrale xy",
    "publisherEmail": "kontakt@hochwasservorhersage.de",
    "licenseName": "CC BY 4.0",
    "licenseUrl": "https://creativecommons.org/licenses/by/4.0/deed.de",
    "schemaUrl": "https://api.example.io/schema-stations.json"
}

HATEOAS-Prinzip ERWEITERT

HATEOAS (Hypermedia as the Engine of Application State) ist ein Prinzip, das es Clients ermöglicht, durch die API anhand interaktiver Links zu navigieren, anstatt feste Endpunkte zu kennen.

Es fördert eine dynamische Interaktion, indem es den Clients Ressourcen und mögliche nächste Schritte in Form von Hyperlinks bereitstellt. Dadurch wird die API intuitiver und anpassungsfähiger an Änderungen im Backend.

Pagination ERWEITERT

Die Offset-Paginierung in APIs ermöglicht es, eine große Datenmenge schrittweise abzurufen, indem man die Anzahl der bereits zurückgegebenen Elemente angibt. Dies erfolgt durch zwei Parameter: limit, um die maximale Anzahl der zurückgegebenen Elemente festzulegen, und offset, um die Startposition für die Ausgabe zu bestimmen. Zum Beispiel gibt ein Offset von 10 in Kombination mit einem Limit von 5 die Datensätze 11 bis 15 zurück.

Feldauswahl ERWEITERT

Die Feldauswahl (auch "Sparse Fieldsets" genannt) ermöglicht es Clients, nur bestimmte Felder einer Ressource anzufordern. Dies reduziert die übertragene Datenmenge und verbessert die Performance, insbesondere bei mobilen Anwendungen oder bei großen Datensätzen.

Funktionsweise

Clients verwenden den Query-Parameter fields mit einer kommagetrennten Liste von gewünschten Feldnamen:

GET /v1/stations?fields=id,name,location

Dieser Request liefert nur die Felder id, name und location im data-Abschnitt der Antwort zurück.

Sortierung ERWEITERT

Die Sortierung ermöglicht es Clients, die Reihenfolge der Ergebnisse nach einem oder mehreren Feldern zu bestimmen.

Funktionsweise

Clients verwenden den Query-Parameter sort mit Feldnamen:

Aufsteigende Sortierung:

GET /v1/stations?sort=name

Sortiert Stationen alphabetisch nach Name (A-Z).

Absteigende Sortierung:

GET /v1/stations?sort=-name

Das Minus-Präfix (-) kennzeichnet eine absteigende Sortierung (Z-A).

Mehrfach-Sortierung

Mehrere Sortierfelder können kommagetrennt angegeben werden. Die Sortierung erfolgt in der angegebenen Reihenfolge (primär, sekundär, etc.):

GET /v1/stations?sort=state,-name

Dieser Request sortiert zuerst nach Bundesland aufsteigend, dann innerhalb jedes Bundeslandes nach Name absteigend.

Standardverhalten

Wenn kein sort-Parameter angegeben wird:

Implementierungshinweise

Beispielanfragen:

# Stationen nach Bundesland und Name sortieren
GET /v1/stations?sort=state,-name

# Neueste Messwerte zuerst
GET /v1/stations/abc123/parameters/water-level/values?sort=-timestamp

# Parameter alphabetisch sortiert, mit Feldauswahl
GET /v1/stations/abc123/parameters?sort=name&fields=id,name,unit

Sicherheit ERWEITERT

Die API kann sowohl öffentlich als auch zugangsbeschränkt implementiert werden. Die Wahl hängt von der Art der bereitgestellten Daten ab. Diese Spezifikation definiert alle gängigen Authentifizierungsmethoden, lässt aber die Wahl dem Implementierer.

Öffentliche API (empfohlen)

Anwendungsfälle:

Konfiguration:

Vorteile:

Zugangsbeschränkte API

Anwendungsfälle:

Empfohlene Authentifizierungsmethoden:

1. API Keys (Einfach)

2. OAuth 2.0 / JWT (Modern)

3. Basic Authentication (Legacy)

CORS Konfiguration

Cross-Origin Resource Sharing (CORS) ist ein Sicherheitsmechanismus, der Web-Anwendungen ermöglicht, APIs auf anderen Domains sicher aufzurufen. Für öffentliche APIs wird CORS empfohlen, um die Nutzung durch browserbasierte Anwendungen zu ermöglichen.

Funktionsweise

Wenn eine Web-Anwendung von https://example.com eine API auf https://api.hydrodaten.de aufruft, sendet der Browser zunächst einen Preflight-Request (HTTP OPTIONS) an die API, um zu prüfen, ob die Cross-Origin-Anfrage erlaubt ist. Die API muss mit entsprechenden CORS-Headern antworten, damit der Browser anschließend die eigentliche Anfrage durchführt.

WICHTIG: CORS wird in der Regel auf Webserver-Ebene (Apache, nginx, Load Balancer) konfiguriert und nicht in der API-Implementierung selbst. Die OPTIONS-Requests werden vom Webserver beantwortet, bevor sie die Anwendung erreichen.

Response-Header (für alle API-Antworten)

Diese Header müssen bei jeder API-Antwort gesetzt werden:

Webserver-Konfiguration

Apache (.htaccess oder VirtualHost):

# Öffentliche API - erlaubt alle Origins
Header always set Access-Control-Allow-Origin "*"
Header always set Access-Control-Allow-Methods "GET, OPTIONS"
Header always set Access-Control-Allow-Headers "Content-Type, Authorization, X-API-Key, Accept-Encoding, If-None-Match"
Header always set Access-Control-Max-Age "86400"
Header always set Access-Control-Expose-Headers "ETag, Cache-Control"

# OPTIONS-Requests sofort mit 204 beantworten
RewriteEngine On
RewriteCond %{REQUEST_METHOD} OPTIONS
RewriteRule ^(.*)$ $1 [R=204,L]
Sicherheitshinweise

Datenformate und Content Negotiation ERWEITERT

HyDAS unterstützt mehrere Ausgabeformate, um unterschiedlichen Anwendungsfällen gerecht zu werden. Das Standardformat ist JSON, aber Implementierer KÖNNEN auch CSV, XML und GeoJSON anbieten, um die Nutzung durch verschiedene Tools und Anwendungen zu erleichtern.

Content Negotiation

Clients können das gewünschte Format auf zwei Arten anfordern:

1. HTTP Accept-Header (RESTful Standard):

GET /v1/stations HTTP/1.1
Host: api.example.io
Accept: text/csv

2. Query-Parameter format (Convenience):

GET /v1/stations?format=application/geo+json

Priorität: Der Query-Parameter format überschreibt den Accept-Header, falls beide angegeben sind. Dies ermöglicht einfaches Testen und Teilen von URLs.

Unterstützte Formate

JSON (Standard) - application/json

CSV - text/csv

Beispiel CSV für /stations:

id,name,type,state,operator,location.lat,location.lon,waterBodyName
a0af41ce-1899-4192-bc70-2fe66581bc8b,Teststation,surfaceWater,BW,Regierungspräsidium xy,52.5163,13.3777,Rhein

Beispiel CSV für /values:

timestamp,value,quality
2025-01-27T12:00:00+01:00,287,good
2025-01-27T12:15:00+01:00,289,good
2025-01-27T12:30:00+01:00,291,good

GeoJSON - application/geo+json

Beispiel GeoJSON für /stations:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [13.3777, 52.5163]
      },
      "properties": {
        "id": "a0af41ce-1899-4192-bc70-2fe66581bc8b",
        "name": "Teststation",
        "type": "surfaceWater",
        "state": "BW",
        "operator": "Regierungspräsidium xy",
        "waterBodyName": "Rhein"
      }
    }
  ]
}

HINWEIS: Bei GeoJSON sind Koordinaten in [longitude, latitude] Reihenfolge (nicht lat/lon).

XML - application/xml

Implementierungshinweise

Content-Type Header setzen:

Content-Type: application/json; charset=utf-8
Content-Type: text/csv; charset=utf-8
Content-Type: application/geo+json; charset=utf-8
Content-Type: application/xml; charset=utf-8

Query-Parameter format:

Entwicklung und Betrieb

Erstellung eines Server-API-Stubs

Mit Hilfe des OpenAPI Generator kann eine Grundimplementierung einer Server-API in verschiedenen Programmiersprachen und Frameworks erstellt werden. Unterstützt werden unter anderem Node.js, Python, Java und viele weitere Technologien. Diese generierte Implementierung dient als guter Ausgangspunkt für die konkrete Umsetzung der API.

# Beispiel: Server-Stub für Node.js generieren
openapi-generator generate \
  -i hydrodaten-api-basic_v01.yaml \
  -g nodejs-express-server \
  -o ./server-stub

Erstellung eines Clients

Für die Client-Entwicklung kann ebenfalls der OpenAPI Generator eingesetzt werden. Dieser generiert Client-Bibliotheken in verschiedenen Programmiersprachen, die eine typsichere Kommunikation mit der API ermöglichen.

# Beispiel: JavaScript-Client generieren
openapi-generator generate \
  -i hydrodaten-api-basic_v01.yaml \
  -g javascript \
  -o ./client-library

Erstellung einer Dokumentation

Basierend auf dieser oder einer angepassten Spezifikation lässt sich eine umfassende HTML-Dokumentation generieren. Hierzu kann beispielsweise das Open Source Tool Redoc verwendet werden.

Testen, Validierung und Monitoring der API

Dieser Bereich umfasst funktionale Tests, Performance-Tests, Sicherheitstests, Schemakonformitätsprüfungen sowie die kontinuierliche Überwachung der API.

Einige der im folgenden genannten Tools lassen sich nahtlos in CI/CD-Pipelines integrieren, wodurch automatisierte Tests bei jeder Codeänderung durchgeführt werden können. Dies gewährleistet eine kontinuierliche Qualitätssicherung während der Weiterentwicklung.

Funktionale Tests und Schemavalidierung

Für funktionale Tests und die Überprüfung der Schemakonformität (entspricht die implementierte API der Spezifikation?) stehen verschiedene Tools zur Verfügung:

Performance-Tests

Die Leistungsfähigkeit einer API kann mit verschiedenen Lasttest-Tools überprüft werden:

Sicherheitstests

Mittels des open source Tools ZAP lassen sich Sicherheitstests durchführen.

Kontinuierliches Monitoring

Für die dauerhafte Überwachung der API-Verfügbarkeit eignen sich verschiedene Monitoring-Services:

Der /health Endpunkt ist der zentrale Mechanismus für operatives Monitoring und sollte von allen Implementierungen bereitgestellt werden. Der Endpunkt kann somit von den Monitoring-Services genutzt werden.

Best Practices für Monitoring:

Weiterhin können Serverlogdateien auf ungünstige Muster überwacht werden, wie z.B. die Häufung fehlerhafter Anfragen.