Zum Inhalt

Datensatzserie fortführen per API

Dieser Guide beschreibt, wie eine CSV-Datei als neuer Eintrag einer Datensatzserie hochgeladen wird. Ist der referenzierte Datensatz bereits Teil einer Datensatzserie, wird die Serie automatisch um den neuen Eintrag erweitert. Besteht noch keine Serie, legt das Backend beim ersten Aufruf automatisch eine neue Datensatzserie an.

Voraussetzungen

  • Client-ID und Client-Secret des Service Accounts liegen vor
  • CSV-Datei ist lokal vorhanden, Encoding und Delimiter sind bekannt
  • Datensatz-ID des zuletzt veröffentlichten Datensatzes der Serie ist bekannt
  • Optional: neue Schema-Version des Schemas ist bekannt (siehe Schema-Repository)

Was ist eine Datensatzserie?

Eine Datensatzserie ist eine logische Gruppierung von Datensätzen, die regelmäßig oder kontinuierlich aktualisiert werden – z. B. monatliche Verkehrszählungen oder jährliche Schulstatistiken. In den Metadatenstandards DCAT-AP (Europa) und DCAT-AP.de (Deutschland) wird dieses Konzept als dcat:DatasetSeries beschrieben.

Alle Einträge der Serie teilen dieselben Metadaten (Katalog, Lizenz, Herausgeber, Kategorien). Jeder neue Eintrag referenziert über previousDatasetId den unmittelbar vorherigen Datensatz in der Serie – dadurch entsteht eine nachvollziehbare chronologische Kette.

Vorgehen

1. Token abrufen

Eine Anleitung zum Abrufen eines gültigen JWT-Tokens findet sich unter Token abrufen.

2. Datensatzserie fortführen

Das Fortführen setzt einen bereits vorhandenen Datensatz voraus, der über die API hochgeladen wurde (siehe Datensatz hochladen per API).

Umgebungen (Produktion/Test)

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.

Endpunkt

POST https://staging-backend.odi.schleswig-holstein.de/upload/csv/append

POST https://staging-backend.staging.frostcluster.da23.dsecurecloud.de/upload/csv/append

Felder

Feld Pflicht Typ Beschreibung
previousDatasetId Pflicht string ID des zuletzt veröffentlichten Datensatzes der Serie
datasetId Pflicht string Frei wählbare ID des neuen Datensatzes
startDate Pflicht string Startdatum des neuen Zeitraums (ISO 8601, z. B. 2024-02-01)
endDate Optional string Enddatum des neuen Zeitraums (ISO 8601)
schemaVersion Optional string Version des Schemas (z. B. 1.1.1) – wird von der bestehenden Serie übernommen
delimiter Pflicht string Trennzeichen der CSV-Datei (z. B. ; oder ,)
encoding Pflicht string Zeichenkodierung (z. B. UTF-8)
quote Pflicht string Anführungszeichen-Zeichen (z. B. ")
file Pflicht binary Die neue CSV-Datei
datasetTitle Pflicht string Titel des neuen Datensatzes
dataSeriesId Pflicht string ID der Datensatzserie – beim Erweitern einer bestehenden Serie wird dieser Wert ignoriert
datasetDescription Pflicht string Beschreibung des neuen Datensatzes – beim Erweitern einer bestehenden Serie wird dieser Wert ignoriert
dataSeriesTitle Pflicht string Titel der Serie – beim Erweitern einer bestehenden Serie wird dieser Wert ignoriert
dataSeriesDescription Pflicht string Beschreibung der Serie – beim Erweitern einer bestehenden Serie wird dieser Wert ignoriert

Serienspezifische Felder

Die Felder dataSeriesId, dataSeriesTitle, datasetDescription und dataSeriesDescription müssen bei jedem Request mitgeschickt werden. Das Backend wertet sie jedoch nur aus, wenn der mit previousDatasetId referenzierte Datensatz noch nicht Teil einer Datensatzserie ist. Wird eine bestehende Serie erweitert, werden diese Felder vom Backend ignoriert.

Empfehlung: datasetId einheitlich benennen

Eine bewährte Konvention ist <thema>-YYYY-MM-DD, z. B. windkraftanlagen-2026-02-01. So lassen sich Einträge einer Serie chronologisch eindeutig zuordnen.

Beispiel-Request

curl --request POST \
  --url https://staging-backend.odi.schleswig-holstein.de/upload/csv/append \
  --header "Authorization: Bearer <access_token>" \
  --header 'content-type: multipart/form-data' \
  --form previousDatasetId=windkraftanlagen-2026 \
  --form datasetId=windkraftanlagen-2026-02-01 \
  --form startDate=2024-02-01 \
  --form 'delimiter=;' \
  --form encoding=UTF-8 \
  --form 'quote="' \
  --form 'file=@/pfad/zu/windkraftanlagen-2026-02-01.csv' \
  --form 'datasetTitle=Windkraftanlagen 01.02.2026' \
  --form datasetDescription=Windkraftanlagen \
  --form dataSeriesId=windkraftanlagen-dataseries \
  --form dataSeriesTitle=Windkraftanlagen

curl --request POST \
  --url https://staging-backend.staging.frostcluster.da23.dsecurecloud.de/upload/csv/append \
  --header "Authorization: Bearer <access_token>" \
  --header 'content-type: multipart/form-data' \
  --form previousDatasetId=windkraftanlagen-2026 \
  --form datasetId=windkraftanlagen-2026-02-01 \
  --form startDate=2024-02-01 \
  --form 'delimiter=;' \
  --form encoding=UTF-8 \
  --form 'quote="' \
  --form 'file=@/pfad/zu/windkraftanlagen-2026-02-01.csv' \
  --form 'datasetTitle=Windkraftanlagen 01.02.2026' \
  --form datasetDescription=Windkraftanlagen \
  --form dataSeriesId=windkraftanlagen-dataseries \
  --form dataSeriesTitle=Windkraftanlagen

Beispiel-Response (Erfolg)

{
  "datasetId": "windkraftanlagen-2026-02-01",
  "dataSeriesUrl": "https://opendata.schleswig-holstein.de/collection/windkraftanlagen-dataseries",
  "datasetUrl": "https://opendata.schleswig-holstein.de/dataset/windkraftanlagen-2026-02-01"
}

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', ...]\"",
      "index": 2,
      "field": "KREIS"
    }
  ]
}

Im Fehlerfall wird ein Validierungsbericht im frictionless-Report-Format zurückgeliefert.

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
413 Datei zu groß Datei übersteigt das serverseitige Größenlimit
500 Interner Serverfehler Kontakt zum ODI-Support aufnehmen

Nächste Schritte

Ein Datensatz in einer Datensatzserie kann bei Bedarf aktualisiert werden.