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 Token abrufen.

2. Datensatz aktualisieren

Endpunkt

PUT https://staging-backend.odi.schleswig-holstein.de/upload/csv/overwrite/{datasetId}?catalogue=opendata-sh

PUT https://staging-backend.odi-stage.schleswig-holstein.de/upload/csv/overwrite/{datasetId}?catalogue=opendata-sh

Felder

datasetId und catalogue werden als Pfad-Parameter in der URL übergeben. 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)
catalogue Pflicht string Katalog-Name des 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. ")
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?catalogue=opendata-sh \
    --header 'authorization: Bearer <access_token>' \
    --header 'content-type: multipart/form-data' \
    --form 'delimiter=;' \
    --form encoding=UTF-8 \
    --form file=@/pfad/zu/windkraftanlagen-2026-05-05.csv

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

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 Token fehlt oder abgelaufen → neuen Token abrufen
403 Keine Berechtigung Service Account hat nicht die erforderliche Rolle
404 Datensatz nicht gefunden datasetId oder catalogue falsch
413 Datei zu groß Datei übersteigt das serverseitige Größenlimit
500 Interner Serverfehler Kontakt zum ODI-Support aufnehmen

Nächste Schritte