Zum Inhalt

Datensatz aktualisieren per API

Dieser Guide beschreibt, wie die CSV-Datei eines bestehenden Datensatzes per API ersetzt wird. Die neue Datei wird dabei automatisch gegen das Schema validiert. Gleichzeitig können der abgedeckte Zeitraum (startDate, endDate) und die Schema-Version (schemaVersion) aktualisiert werden.

Alle anderen Metadaten – Titel, Beschreibung, Lizenz, Herausgeber, Kategorien und Raumbezug – bleiben unverändert.

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

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

https://staging-backend.staging.frostcluster.da23.dsecurecloud.de/docs

Umgebungen

Alle Requests in diesem Guide sind für beide Umgebungen verfügbar. Wähle die passende Umgebung über die Tabs bei den Beispiel-Requests aus. Die Zugangsdaten (Client-ID, Client-Secret) sind umgebungsspezifisch und werden vom ODI-Team bereitgestellt.

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

Eine Anleitung zum Abrufen eines gültigen JWT-Tokens findet sich unter 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.staging.frostcluster.da23.dsecurecloud.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.staging.frostcluster.da23.dsecurecloud.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