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: staging-backend.odi.schleswig-holstein.de/docs

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

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

Token abrufen (Keycloak Service Account)¶

Alle schreibenden API-Requests erfordern ein gültiges JWT-Token für diesen 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.

Datensatz aktualisieren¶

Felder (Request Body)¶

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.

Beispiel-Request¶

curl -X PUT \
  "https://staging-backend.odi.schleswig-holstein.de/upload/csv/overwrite/<datasetId>?catalogue=opendata-sh" \
  -H "Authorization: Bearer <access_token>" \
  -F "delimiter=;" \
  -F "encoding=UTF-8" \
  -F 'quote="' \
  -F "file=@/pfad/zur/neuen-datei.csv" \
  -F "schemaVersion=1.2.0" \
  -F "startDate=2024-01-01T00:00:00" \
  -F "endDate=2024-12-31T00:00:00"

Beispiel-Response (Erfolg)¶

{}

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¶

Nächste Schritte¶

• Datensatzserie fortführen per API – neuen Zeitraum-Eintrag in einer bestehenden Serie anlegen (POST /upload/csv/append)