Zum Inhalt

Datensatz aktualisieren per API

Liegt zu einem bereits veröffentlichten Datensatz eine neue CSV-Datei vor, kann sie per API ausgetauscht werden. Auch hier prüft das Backend die Datei vor der Übernahme gegen das Schema.

Die vollständige API-Referenz ist in der Swagger-Dokumentation verfügbar:

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

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

Umgebungen

Produktion oder Test lässt sich bei jedem Beispiel-Request über die Tabs auswählen.

Was wird aktualisiert?

Durch diesen Request wird zwingend ersetzt:

  • CSV-Datei – die neue Datei ersetzt die bisherige Distribution des Datensatzes

Optional können dabei auch überschrieben werden:

  • Zeitraum (startDate / endDate) – DCAT-AP: dct:temporal → dcat:startDate / dcat:endDate
  • Schema-Version (schemaVersion) – bestimmt, gegen welche Version des Schemas die neue Datei validiert wird

Nicht änderbar durch diesen Request:

  • Titel, Beschreibung, Lizenz, Herausgeber, Kategorien, Raumbezug

Abgrenzung: Aktualisieren vs. Fortführen

Wenn neue Daten zu einer bestehenden Datensatzserie hinzugefügt werden sollen (z. B. ein neuer Monatseintrag), ist der Endpunkt POST /upload/csv/append zu verwenden. Siehe: Datensatzserie fortführen per API

Voraussetzungen

  • Client-ID und Client-Secret des Service Accounts liegen vor
  • datasetId des zu aktualisierenden Datensatzes ist bekannt
  • Neue CSV-Datei ist lokal vorhanden; Encoding, Delimiter und Quote-Zeichen sind bekannt
  • Optional: neue schemaVersion, falls die Datei gegen eine neuere Schema-Version validiert werden soll – wie die Schema-Version ermittelt wird, ist unter Datensatz hochladen per API – Schema-ID ermitteln beschrieben

Vorgehen

1. Token abrufen

Wie aus Client-ID und Client-Secret ein JWT-Token wird, zeigt API-Token abrufen.

2. Datensatz aktualisieren

Endpunkt

PUT https://staging-backend.odi.schleswig-holstein.de/upload/csv/overwrite/{datasetId}

PUT https://staging-backend.odi-stage.schleswig-holstein.de/upload/csv/overwrite/{datasetId}

Felder

datasetId wird als Pfad-Parameter in der URL übergeben. Katalog und Schema-ID übernimmt das Backend vom bestehenden Datensatz. Die CSV-Datei und alle weiteren Felder werden als multipart/form-data im Body übergeben.

Feld Pflicht Typ Beschreibung
{datasetId} Pflicht string ID des zu aktualisierenden Datensatzes (Pfad-Parameter in der URL)
file Pflicht binary Die neue CSV-Datei – ersetzt die bisherige Distribution
delimiter Pflicht string Trennzeichen der CSV-Datei (z. B. ; oder ,)
encoding Pflicht string Zeichenkodierung (z. B. UTF-8)
quote Optional string Anführungszeichen-Zeichen (z. B. ")
escapeChar Optional string Escape-Zeichen innerhalb von Feldern in Anführungszeichen (z. B. \)
schemaVersion Optional string Schema-Version für die Validierung (z. B. 1.2.0) – schemaId bleibt fest
startDate Optional string Neues Startdatum des Zeitraums (ISO 8601) – DCAT-AP: dcat:startDate
endDate Optional string Neues Enddatum des Zeitraums (ISO 8601) – DCAT-AP: dcat:endDate

Info

Die schemaVersion bestimmt, gegen welche Version des Schemas die neue Datei validiert wird. Die Schema-ID (schemaId) kann nicht geändert werden.

Beispiel-Request

curl --request PUT \
    --url https://staging-backend.odi.schleswig-holstein.de/upload/csv/overwrite/windkraftanlagen-05-05-2026 \
    --header 'authorization: Bearer <access_token>' \
    --header 'content-type: multipart/form-data' \
    --form-string 'delimiter=;' \
    --form encoding=UTF-8 \
    --form 'file=@/pfad/zu/windkraftanlagen-2026-05-05.csv;type=text/csv'

curl --request PUT \
    --url https://staging-backend.odi-stage.schleswig-holstein.de/upload/csv/overwrite/windkraftanlagen-05-05-2026 \
    --header 'authorization: Bearer <access_token>' \
    --header 'content-type: multipart/form-data' \
    --form-string 'delimiter=;' \
    --form encoding=UTF-8 \
    --form 'file=@/pfad/zu/windkraftanlagen-2026-05-05.csv;type=text/csv'

curl: Trennzeichen und Dateityp

Zwei Angaben im Beispiel-Request sind nötig, damit curl die Felder richtig überträgt:

  • --form-string 'delimiter=;' statt --form: Bei --form wertet curl ein Semikolon als Trennzeichen für eigene Optionen aus und sendet das Feld leer.
  • ;type=text/csv hinter dem Dateipfad: Ohne diese Angabe sendet curl die Datei als application/octet-stream, und das Backend lehnt sie mit HTTP 400 ab.

Beispiel-Response (Erfolg)

{
  "datasetId": "windkraftanlagen-05-05-2026",
  "datasetUrl": "https://opendata.schleswig-holstein.de/dataset/windkraftanlagen-05-05-2026"
}

Beispiel-Response (Fehlerfall - Validierung fehlgeschlagen)

{
  "status": "error",
  "type": "invalid file",
  "message": "Validation of Csv-File was not valid!",
  "context": "CsvUploadService",
  "errors": [
    {
      "description": "The cell \"Harburg\" in row at position \"2\" and field \"KREIS\" at position \"1\" does not conform to a constraint: constraint \"enum\" is \"['Dithmarschen', 'Kiel', 'Lübeck', 'Nordfriesland', 'Hzgt.Lauenburg', 'Ostholstein', 'Plön', 'Pinneberg', 'Rendsburg-Eckernförde', 'Segeberg', 'Schleswig-Flensburg', 'Steinburg', 'Stormarn']\"",
      "index": 2,
      "field": "KREIS"
    }
  ]
}

Fehlercodes

HTTP-Status Bedeutung Mögliche Ursache / Lösung
400 Ungültige Anfrage Pflichtfeld fehlt, falsches Format oder CSV entspricht nicht dem Schema
401 Nicht authentifiziert Access-Token fehlt oder ist abgelaufen → neuen Token abrufen. Oder dem Service Account ist kein gültiger ckan-token zugeordnet → Zugriff prüfen
403 Keine Berechtigung Das CKAN-Konto hinter dem ckan-token hat im Datenkatalog keine Schreibrechte für den Herausgeber
404 Datensatz nicht gefunden datasetId falsch
413 Datei zu groß Datei übersteigt das serverseitige Größenlimit von 300 MB
500 Interner Serverfehler Kontakt zum ODI-Support aufnehmen

Nächste Schritte