Datensatzserie fortführen per API¶

Dieser Guide beschreibt, wie eine bestehende Datensatzserie (z. B. monatliche Berichte) um einen neuen Zeitraum-Eintrag erweitert wird.

Eine Datensatzserie fasst mehrere zeitlich aufeinander folgende Datensätze unter einer gemeinsamen Datensatzserien-Entität zusammen. Die bestehenden Metadaten (Katalog, Lizenz, Herausgeber, Kategorien) werden von der Serie übernommen – nur die neue CSV-Datei, der neue Zeitraum und die Referenz auf den vorherigen Datensatz müssen angegeben werden.

Das Fortführen setzt einen bereits vorhandenen Datensatz voraus, der über die API hochgeladen wurde. Ist dieser Datensatz bereits Teil einer Datensatzserie, wird die Serie um den neuen Eintrag erweitert. Ist er noch nicht Teil einer Serie, legt das Backend automatisch eine neue Datensatzserie an und fügt beide Datensätze ein.

Die vollständige API-Referenz ist in der Swagger-Dokumentation verfügbar: staging-backend.odi.schleswig-holstein.de/docs

Voraussetzungen¶

• Client-ID und Client-Secret des Service Accounts liegen vor
• datasetId des zuletzt veröffentlichten Datensatzes der Serie (previousDatasetId) ist bekannt
• CSV-Datei ist lokal vorhanden, Encoding und Delimiter sind bekannt
• Optional: 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.

Token abrufen (Keycloak Service Account)¶

Alle schreibenden API-Requests erfordern ein gültiges JWT-Token, für das ein Service Account notwendig ist.

Die Zugangsdaten bestehen aus einer Client-ID und einem Client-Secret.

Request:

curl -X POST \
  "https://keycloak.odi.schleswig-holstein.de/realms/open-data-infrastruktur/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<client-id>" \
  -d "client_secret=<client-secret>"

Beispiel-Response:

{
  "access_token": "eyJ...",
  "expires_in": 300,
  "token_type": "Bearer"
}

Den Wert von access_token im nächsten Schritt als Bearer-Token verwenden.

Datensatzserie fortführen¶

Endpunkt¶

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

Felder (Request Body)¶

* dataSeriesId ist nur erforderlich, wenn das Backend eine neue Datensatzserie anlegen soll.

Beispiel-Request¶

curl -X POST \
  "https://staging-backend.odi.schleswig-holstein.de/upload/csv/append" \
  -H "Authorization: Bearer <access_token>" \
  -F "previousDatasetId=<vorheriger-datensatz-id>" \
  -F "datasetId=mein-datensatz-2024-02" \
  -F "startDate=2024-02-01T00:00:00" \
  -F "schemaVersion=1.1.1" \
  -F "delimiter=;" \
  -F "encoding=UTF-8" \
  -F 'quote="' \
  -F "file=@/pfad/zur/neuen-datei.csv"

Beispiel-Response (Erfolg)¶

{
  "datasetId": "mein-datensatz-2024-02"
}

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¶

Nächste Schritte¶

• Datensatz aktualisieren per API – eine bestehende CSV-Version ersetzen (PUT /upload/csv/overwrite/{datasetId})
• Datensatz hochladen per API – einen neuen Datensatz (außerhalb einer Serie) anlegen