CKAN Action API

Version: In Entwicklung

Aufgabe der CKAN API

Die API beschreibt und verwaltet Katalogobjekte:

Datensätze beziehungsweise packages,
Ressourcen und deren Download- oder API-Endpunkte,
Organisationen und Gruppen,
Harvesting-Quellen,
tabellarische Inhalte im optionalen CKAN DataStore.

CKAN ist nicht automatisch der Speicherort der in einem Datensatz beschriebenen Fachdaten. Eine Ressource kann beispielsweise auf MinIO, einen GeoServer-Dienst oder eine externe URL verweisen.

API-Aufruf

Action-Namen werden an die Basis-URL angehängt:

curl --fail --show-error \
  --get \
  "https://ckan.<DOMAIN>/api/3/action/package_search" \
  --data-urlencode "q=mobility" \
  --data-urlencode "rows=20"

Eine erfolgreiche CKAN-Antwort enthält üblicherweise:

{
  "success": true,
  "result": {}
}

HTTP 200 allein genügt deshalb nicht als fachliche Erfolgskontrolle; Clients müssen zusätzlich success auswerten.

Wichtige Actions

Action	Aufgabe	Typischer Zugriff
`package_search`	Datensätze suchen	häufig öffentlich
`package_show`	einzelnen Datensatz mit Ressourcen lesen	häufig öffentlich
`resource_show`	Metadaten einer Ressource lesen	häufig öffentlich
`organization_list`	Organisationen auflisten	abhängig von CKAN-Konfiguration
`datastore_search`	tabellarische DataStore-Ressource abfragen	abhängig von Ressource
`package_create`	Datensatz anlegen	authentifiziert und berechtigt
`package_update`	Datensatz ändern	authentifiziert und berechtigt

Authentifizierte Änderungen

Für schreibende Actions wird ein von CKAN ausgegebenes API-Token verwendet:

curl --fail --show-error \
  --request POST \
  "https://ckan.<DOMAIN>/api/3/action/package_create" \
  --header "Authorization: <CKAN_API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "beispiel-datensatz",
    "title": "Beispiel-Datensatz",
    "owner_org": "<ORGANIZATION_ID>"
  }'

Das Token übernimmt die CKAN-Berechtigungen seines Benutzers. Es ist kein Keycloak Access Token und verwendet nicht die APISIX-Scopes api:read, api:write oder api:delete.

Keycloak und CKAN nicht verwechseln

Die bereitgestellte CKAN-Oberfläche kann Keycloak für die Browseranmeldung verwenden. Nach der Anmeldung gelten jedoch weiterhin Organisationen, Rollen und Berechtigungen von CKAN. Für direkte Action-API-Aufrufe ist das CKAN-API-Token maßgeblich.

DataStore und Ressourcen

datastore_search funktioniert nur für Ressourcen, die in den CKAN DataStore geladen wurden. Bei einer normalen URL-, Datei- oder GeoServer-Ressource muss der im Ressourcenobjekt angegebene Endpunkt direkt verwendet werden.

Metadatenstandards

Die Standardkonfiguration aktiviert unter anderem DCAT-/DCAT-DE-Erweiterungen. DCAT-Feeds und Harvesting ergänzen die CKAN Action API, ersetzen sie aber nicht. Welche Profile und Endpunkte veröffentlicht werden, hängt von den aktivierten CKAN-Plugins und der mandantenspezifischen Konfiguration ab.

Weiterführend:

Offizielle API-Referenz

Die CKAN-Dokumentation beschreibt den vollständigen Aufbau der Action API, Authentifizierung, Fehlerbehandlung sowie die FileStore- und DataStore-Erweiterungen. Die Referenz ist auf die in der UDSP verwendete CKAN-Versionslinie 2.11 abgestimmt.

Externe Referenz

Offizielle Referenz für Actions, API-Token, Rückgaben sowie FileStore und DataStore.

CKAN API Guide öffnen

Aufgabe der CKAN API​

API-Aufruf​

Wichtige Actions​

Authentifizierte Änderungen​

Keycloak und CKAN nicht verwechseln​

DataStore und Ressourcen​

Metadatenstandards​

Offizielle API-Referenz​