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.

Übersicht¶

API	Version	Zweck	Swagger-Doku
Schema-Repository API	2.8.2	Schema-Verwaltung	/docs
Staging API	1.23.10	Datensatz-Upload & -Verwaltung	/docs
Metadata API	1.0	Metadaten-Referenzdaten	/docs
CKAN-Adapter API	1.0.0	CKAN-Kommunikation	/docs
Frictionless API	0.1.0	Validierung & Extraktion	/docs

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 (Service Account / Client-Credentials-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 \
  --data grant_type=client_credentials \
  --data client_secret=<CLIENT_SECRET>

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¶

Methode	Pfad	Beschreibung
`POST`	`/realms/open-data-infrastruktur/protocol/openid-connect/token`	Access-Token anfordern (Password- oder Client-Credentials-Flow)
`POST`	`/realms/open-data-infrastruktur/protocol/openid-connect/token`	Access-Token erneuern (`grant_type=refresh_token`)
`POST`	`/realms/open-data-infrastruktur/protocol/openid-connect/logout`	Token / Session invalidieren

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:

Code	Bedeutung
200	OK – Anfrage erfolgreich
201	Created – Ressource erfolgreich angelegt
400	Bad Request – Validierungsfehler in der Anfrage
401	Unauthorized – Kein oder ungültiger Token
403	Forbidden – Fehlende Berechtigung
404	Not Found – Ressource nicht gefunden

Schema-Repository API¶

ProduktionTest

Version 2.8.2 · OAS 3.0 · Lizenz: MIT

Swagger-UI: https://schema-repo-backend.odi.schleswig-holstein.de/docs

Version 2.8.2 · OAS 3.0 · Lizenz: MIT

Swagger-UI: https://schema-repo-backend.odi-stage.schleswig-holstein.de/api/docs

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¶

Methode	Pfad	Beschreibung
`GET`	`/schemas`	Alle Schemas auflisten
`POST`	`/schemas`	Neues Schema anlegen
`POST`	`/schemas/synchronize`	Schemas synchronisieren
`GET`	`/schemas/groups`	Schema-Gruppen abrufen
`POST`	`/schemas/searchByHeader`	Schema per Header suchen
`GET`	`/schemas/{id}`	Schema abrufen
`PUT`	`/schemas/{id}`	Schema aktualisieren
`GET`	`/schemas/{id}/tags`	Tags eines Schemas abrufen
`GET`	`/schemas/{id}/{version}`	Bestimmte Version abrufen
`GET`	`/schemas/{id}/{version}/{file}`	Bestimmte Datei einer Version abrufen

Datenmodelle: Schema, SchemaCreateDto, GitFile, CreateSchemaRequest, UpdateSchemaRequest

Beispiel: Alle Schemas auflisten¶

ProduktionTest

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

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

Staging API¶

ProduktionTest

Version 1.23.10 · OAS 3.0 · Lizenz: MIT

Swagger-UI: https://staging-backend.odi.schleswig-holstein.de/docs

Version 1.23.10 · OAS 3.0 · Lizenz: MIT

Swagger-UI: https://staging-backend.odi-stage.schleswig-holstein.de/docs

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).

Authentifizierung erforderlich

Alle 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¶

CSV

Methode	Pfad	Beschreibung
`POST`	`/upload/csv`	Neuen CSV-Datensatz hochladen
`PUT`	`/upload/csv/overwrite/{datasetId}`	CSV-Datensatz aktualisieren
`POST`	`/upload/csv/append`	Datensatz fortführen (append)
`PUT`	`/upload/csv/complete/{datasetId}`	CSV-Datensatz vervollständigen

GeoJSON

Methode	Pfad	Beschreibung
`POST`	`/upload/geojson`	GeoJSON-Datensatz hochladen
`PUT`	`/upload/geojson/overwrite/{datasetId}`	GeoJSON-Datensatz ersetzen

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¶

ProduktionTest

Version 1.0 · OAS 3.0 · Lizenz: MIT

Swagger-UI: https://metadata-service.odi.schleswig-holstein.de/docs

Version 1.0 · OAS 3.0 · Lizenz: MIT

Swagger-UI: https://metadata-service.odi-stage.schleswig-holstein.de/docs

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

Methode	Pfad	Beschreibung
`GET`	`/publisher`	Alle Herausgeber auflisten
`POST`	`/publisher`	Neuen Herausgeber anlegen
`GET`	`/publisher/{identifier}`	Herausgeber abrufen
`DELETE`	`/publisher/{identifier}`	Herausgeber löschen

Kategorien

Methode	Pfad	Beschreibung
`GET`	`/categories`	Alle Kategorien auflisten
`GET`	`/categories/{identifier}`	Kategorie abrufen

Datenkataloge

Methode	Pfad	Beschreibung
`GET`	`/catalogs`	Alle Kataloge auflisten
`GET`	`/catalogs/{identifier}`	Katalog abrufen

Lizenzen

Methode	Pfad	Beschreibung
`GET`	`/licenses`	Alle Lizenzen auflisten
`GET`	`/licenses/{identifier}`	Lizenz abrufen

Raumbezug

Methode	Pfad	Beschreibung
`GET`	`/places`	Alle Raumbezüge auflisten
`GET`	`/places/{identifier}`	Raumbezug abrufen

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

CKAN-Adapter API¶

ProduktionTest

Version 1.0.0 · OAS 3.0

Swagger-UI: https://ckan-service.odi.schleswig-holstein.de/docs

Version 1.0.0 · OAS 3.0

Swagger-UI: https://ckan-service.odi-stage.schleswig-holstein.de/docs

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

Methode	Pfad	Beschreibung
`POST`	`/dataset/{catalogue}`	Datensatz anlegen
`PUT`	`/dataset/publish/{catalogue}/{datasetId}`	Datensatz veröffentlichen
`PUT`	`/dataset/{datasetId}`	Datensatz aktualisieren
`GET`	`/dataset/{datasetId}`	Datensatz abrufen
`GET`	`/dataset/{datasetId}/distributions`	Distributionen eines Datensatzes abrufen
`GET`	`/dataset`	Alle Datensätze auflisten

Distribution

Methode	Pfad	Beschreibung
`POST`	`/distribution/{catalogue}/{datasetId}`	Datei als Distribution hochladen
`POST`	`/distribution/{catalogue}/{datasetId}/link-to`	Link als Distribution anlegen
`PUT`	`/distribution/{catalogue}/{distributionId}`	Distribution aktualisieren
`PUT`	`/distribution/{catalogue}/{distributionId}/file`	Datei einer Distribution ersetzen
`PUT`	`/distribution/{catalogue}/{distributionId}/link-to`	Link einer Distribution ersetzen

Datensatzserie

Methode	Pfad	Beschreibung
`POST`	`/dataseries/{catalogue}`	Datensatzserie anlegen
`GET`	`/dataseries/{catalogue}/{dataSeriesId}`	Datensatzserie abrufen
`POST`	`/dataseries/{catalogue}/{dataSeriesId}/add`	Datensatz zur Serie hinzufügen
`PUT`	`/dataseries/{catalogue}/{dataSeriesId}/dataset/{id}`	Datensatz in Serie aktualisieren

Vokabular & Kataloge

Methode	Pfad	Beschreibung
`GET`	`/vocabulary/{id}`	Vokabular abrufen
`GET`	`/catalogue`	Alle Kataloge auflisten

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

Frictionless API¶

ProduktionTest

Version 0.1.1 · OAS 3.1 · FastAPI

Swagger-UI: https://frictionless.odi.schleswig-holstein.de/docs

Version 0.1.1 · OAS 3.1 · FastAPI

Swagger-UI: https://frictionless-backend.odi-stage.schleswig-holstein.de/docs

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: Keine Authentifizierung erforderlich.

Endpunkte¶

Methode	Pfad	Beschreibung
`GET`	`/`	Healthcheck
`POST`	`/validate/csv`	CSV-Datei gegen ein Schema validieren (empfohlen)
`POST`	`/validate/schema`	Schema-Descriptor validieren
`POST`	`/validate/data`	JSON-Datensatz gegen ein Schema validieren (deprecated)
`POST`	`/validate`	Alias für `/validate/data` (deprecated)
`POST`	`/describe/csv`	Schema aus CSV-Datei ableiten
`POST`	`/describe/json`	Schema aus JSON-Objekt ableiten
`POST`	`/validate_resource`	Ressource per URL validieren
`GET`	`/validate_resource`	Ressource per URL validieren (GET)
`GET`	`/extract/{resource_url}`	Daten aus einer Ressource extrahieren

CSV-Datei validieren: `POST /validate/csv`¶

Validiert eine CSV-Datei direkt gegen ein Frictionless-Schema. Dies ist der empfohlene Endpunkt für die CSV-Validierung, da die Datei als Binärdatei übertragen wird und kein JSON-Roundtrip stattfindet.

Request (multipart/form-data)

Feld	Typ	Pflicht	Beschreibung
`file`	`File`	✅	CSV-Datei
`schema`	`string`	✅	Frictionless-Schema als JSON-String
`delimiter`	`string`	—	Trennzeichen (z. B. `;`, `,`, `\t`). Wird automatisch erkannt, wenn nicht angegeben.
`encoding`	`string`	—	Zeichenkodierung der Datei (z. B. `UTF-8`, `Windows-1252`). Wird automatisch erkannt, wenn nicht angegeben.

Vollständige Validierung

Alle Zeilen der Datei werden geprüft – es gibt kein Fehler-Limit.

Response-Header bei deprecation

/validate/data gibt zusätzlich folgende HTTP-Header zurück: Deprecation: true, Sunset: 2027-01-01, Link: </validate/csv>; rel="successor-version"

ProduktionTest

curl --request POST \
  --url 'https://frictionless.odi.schleswig-holstein.de/validate/csv' \
  --header 'accept: application/json' \
  --form 'file=@datei.csv;type=text/csv' \
  --form 'schema={"fields":[{"name":"id","type":"integer"},{"name":"name","type":"string"}]}' \
  --form 'delimiter=;' \
  --form 'encoding=UTF-8'

curl --request POST \
  --url 'https://frictionless-backend.odi-stage.schleswig-holstein.de/validate/csv' \
  --header 'accept: application/json' \
  --form 'file=@datei.csv;type=text/csv' \
  --form 'schema={"fields":[{"name":"id","type":"integer"},{"name":"name","type":"string"}]}' \
  --form 'delimiter=;' \
  --form 'encoding=UTF-8'

Response

{
  "valid": true,
  "report": {
    "valid": true,
    "stats": { "tasks": 1, "errors": 0 },
    "tasks": [{ "valid": true, "errors": [] }]
  }
}

Bei Fehlern enthält report.tasks[0].errors eine Liste von Fehlerobjekten mit rowNumber, fieldName, type und message.

Schema aus CSV ableiten: `POST /describe/csv`¶

Leitet automatisch ein Frictionless-Schema aus einer CSV-Datei ab (Spaltentypen, Namen).

Request (multipart/form-data)

Feld	Typ	Pflicht	Beschreibung
`file`	`File`	✅	CSV-Datei
`encoding`	`string`	—	Zeichenkodierung (z. B. `Windows-1252`). Wichtig bei nicht-UTF-8-kodierten Dateien, da andernfalls die Spaltennamen falsch erkannt werden können.

ProduktionTest

curl --request POST \
  --url 'https://frictionless.odi.schleswig-holstein.de/describe/csv' \
  --header 'accept: application/json' \
  --form 'file=@datei.csv;type=text/csv' \
  --form 'encoding=Windows-1252'

curl --request POST \
  --url 'https://frictionless-backend.odi-stage.schleswig-holstein.de/describe/csv' \
  --header 'accept: application/json' \
  --form 'file=@datei.csv;type=text/csv' \
  --form 'encoding=Windows-1252'

Ressource per URL validieren: `GET /validate_resource`¶

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

ProduktionTest

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'

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

API Referenz¶

Inhalt¶

Übersicht¶

Authentifizierung & Keycloak¶

Token anfordern (Service Account / Client-Credentials-Flow)¶

Token erneuern¶

Keycloak-Endpunkte¶

Konventionen¶

Schema-Repository API¶

Endpunkte¶

Beispiel: Alle Schemas auflisten¶

Staging API¶

Endpunkte¶

Metadata API¶

Endpunkte¶

CKAN-Adapter API¶

Endpunkte¶

Frictionless API¶

Endpunkte¶

CSV-Datei validieren: POST /validate/csv¶

Schema aus CSV ableiten: POST /describe/csv¶

Ressource per URL validieren: GET /validate_resource¶

CSV-Datei validieren: `POST /validate/csv`¶

Schema aus CSV ableiten: `POST /describe/csv`¶

Ressource per URL validieren: `GET /validate_resource`¶