API Referenz¶

Die ODI-Plattform stellt mehrere REST-APIs bereit, die zusammen den vollständigen Lebenszyklus von Open-Data-Datensätzen abdecken – von der Schema-Verwaltung über den Datensatz-Upload bis zur Veröffentlichung im CKAN-Datenkatalog. Alle APIs folgen dem OpenAPI-Standard (OAS 3.0 / 3.1) und sind über eine interaktive Swagger-UI erreichbar.

Für den Zugriff auf schreibende Endpunkte ist eine JWT-Authentifizierung erforderlich. Siehe Authentifizierung & Keycloak.

Inhalt¶

• Übersicht
• Authentifizierung & Keycloak
• Konventionen
• Schema-Repository API
• Staging API
• Metadata API
• CKAN-Adapter API
• Frictionless API

Übersicht¶

Authentifizierung & Keycloak¶

Alle ODI-APIs verwenden Keycloak als Identity Provider. Schreibende Endpunkte erfordern einen gültigen JWT-Token.

Für die Einrichtung eines Service Accounts für den programmatischen API-Zugriff siehe: Programmatischen API-Zugriff einrichten

Basis-URL: https://keycloak.odi.schleswig-holstein.de
Realm: open-data-infrastruktur
Client-ID: odi-api-client

Token anfordern (Password-Flow)¶

curl --request POST \
  --url https://keycloak.odi.schleswig-holstein.de/realms/open-data-infrastruktur/protocol/openid-connect/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data client_id=odi-api-client \
  --data grant_type=password \
  --data username=<BENUTZERNAME> \
  --data 'password=<PASSWORT>'

Token erneuern¶

curl --request POST \
  --url https://keycloak.odi.schleswig-holstein.de/realms/open-data-infrastruktur/protocol/openid-connect/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data client_id=odi-api-client \
  --data grant_type=refresh_token \
  --data 'refresh_token=<REFRESH_TOKEN>'

Keycloak-Endpunkte¶

Konventionen¶

• Alle APIs geben JSON zurück (Content-Type: application/json)
• Pfadparameter werden in {geschweifte Klammern} angegeben
• Datumsangaben folgen dem ISO-8601-Format (z. B. 2026-04-29 oder 2026-04-29T14:30:00Z)
• Relevante HTTP-Statuscodes:

Schema-Repository API¶

Verwaltung von Validierungsschemas: anlegen, abrufen und versionieren. Schemas werden im Staging-Backend zur Validierung von Datensätzen referenziert.

Authentifizierung: Lesende Endpunkte sind öffentlich zugänglich. Schreibende Endpunkte (POST, PUT) erfordern einen gültigen JWT-Token. Den Token nach der Anmeldung via Keycloak als Bearer-Token im Authorization-Header mitsenden:

Authorization: Bearer <access_token>

Endpunkte¶

Datenmodelle: Schema, SchemaCreateDto, GitFile, CreateSchemaRequest, UpdateSchemaRequest

Beispiel: Alle Schemas auflisten¶

curl --request GET \
  --url https://schema-repo-backend.odi.schleswig-holstein.de/schemas \
  --header 'accept: application/json'

Staging API¶

Zentraler Einstiegspunkt für das Hochladen, Aktualisieren und Fortführen von Datensätzen (CSV, GeoJSON, CSV mit Geo-Informationen). Verbindet intern die Schema-Repository API (Validierung) mit dem CKAN-Adapter API (Veröffentlichung).

Authorization: Bearer <access_token>

Endpunkte¶

CSV

GeoJSON

Datenmodelle: NifiRequest, JsonValidationRequest, CsvUploadRequest, CsvUploadResult, CsvReplaceRequest, CsvCompleteRequest, AppendCsvRequest, GeoJsonRequest, GeoJsonReplaceRequest

Detaillierte Anleitungen: Datensatz hochladen per API · Datensatz aktualisieren per API · Datensatzserie fortführen per API

Metadata API¶

Bereitstellung von Referenzdaten im Open-Data-Kontext: Herausgeber, Kategorien, Datenkataloge, Lizenzen und Raumbezüge. Die zurückgegebenen IDs werden beim Datensatz-Upload im Staging-Backend als Metadatenfelder benötigt.

Authentifizierung: Lesende Endpunkte sind öffentlich zugänglich. Schreibende und löschende Endpunkte (POST, DELETE) erfordern einen gültigen JWT-Token. Den Token nach der Anmeldung via Keycloak als Bearer-Token im Authorization-Header mitsenden:

Authorization: Bearer <access_token>

Endpunkte¶

Herausgeber

Kategorien

Datenkataloge

Lizenzen

Raumbezug

Datenmodelle: Publisher, PublisherCreateDto, Category, Catalog, Licence, Place

CKAN-Adapter API¶

Abstraktionsschicht zur Kommunikation mit dem CKAN-Datenkatalog. Verwaltet Datensätze, Distributionen, Datensatzserien, Kataloge und kontrollierte Vokabulare. Wird in der Regel vom Staging-Backend intern aufgerufen.

Authentifizierung: Alle schreibenden Endpunkte erfordern einen gültigen JWT-Token. Den Token nach der Anmeldung via Keycloak als Bearer-Token im Authorization-Header mitsenden:

Authorization: Bearer <access_token>

Endpunkte¶

Datensatz

Distribution

Datensatzserie

Vokabular & Kataloge

Datenmodelle: CreateDatasetRequest, CreateDatasetResponse, PublishDatasetResponse, UpdateDatasetRequest, DistributionCreateFileUploadDto, DataseriesResponse

Frictionless API¶

Validierung und Extraktion von Datensätzen auf Basis des Frictionless-Data-Standards. Wird vom Staging-Backend intern für die Datenvalidierung genutzt, kann aber auch direkt angesprochen werden.

Authentifizierung: Für den direkten Aufruf den JWT-Token als Bearer-Token im Authorization-Header mitsenden:

Authorization: Bearer <access_token>

Endpunkte¶

Datenmodelle: ValidationRequest, HTTPValidationError, ValidationError

Beispiel: Ressource per URL validieren¶

Der Parameter resource_url erwartet eine HTTP-URL zu einer tabellarischen Datenressource (z. B. eine CSV-Datei), die öffentlich erreichbar ist.

curl --request GET \
  --url 'https://frictionless.odi.schleswig-holstein.de/validate_resource?resource_url=https%3A%2F%2Fexample.com%2Fdatei.csv' \
  --header 'accept: application/json'