Die REST-API als Datenschnittstelle #

Diese Seite richtet sich an Entwickler und Administratoren, die möchten, dass Maschinen Datensatzbeschreibungen und Dateilinks direkt lesen. Exponential stellt aus einer Erweiterung, ezprestapi, eine REST-API für Inhalte unter /api/ezp/v1/... und /api/ezp/v2/... bereit. Alles Folgende stammt aus REST-API v1 und v2 und Persönliche API-Schlüssel.

Inhalt #

1. Was sie liefert
2. Standardmäßig mit Authentifizierung
3. Für anonyme Leser öffnen
4. Aufrufe, die ein Datenclient macht
5. Was sie nicht ist
6. Datensätze aus einem anderen System aktuell halten
7. Bevor Sie sie ankündigen

Was sie liefert #

Lesezugriffe antworten unter v1 und v2; Schreibzugriffe nur unter v2. Die Antworten sind JSON.

Ein mit list gelesener Katalogordner liefert die Datensätze; jeder mit fields gelesene Datensatz liefert seine Metadaten; das Dateifeld jeder Distribution liefert die Dateiinformationen.

Standardmäßig mit Authentifizierung #

rest.ini [Authentication] RequireAuthentication=enabled ist die Voreinstellung: Jede Inhaltsroute braucht einen Benutzer, entweder mit einem OAuth2-Token (registriert unter Setup > oAuth-Verwaltung) oder mit einem persönlichen API-Schlüssel, gesendet als Authorization: Bearer expk_.... Jeder Lesezugriff prüft die Richtlinie content/read des Benutzers, sodass ein Client nie mehr sieht, als dieser Benutzer darf.

Für anonyme Leser öffnen #

RequireAuthentication=disabled lässt jede Anfrage als DefaultUserID laufen, oder als anonymer Benutzer, wenn diese Einstellung leer ist; die Rechteprüfungen gelten weiter, sodass anonyme Clients genau das sehen, was anonyme Besucher der Website sehen. Bevor Sie das ändern:

1. Stellen Sie sicher, dass die Rolle Anonymous nur öffentliche Sektionen liest (Rechte für Besucher).
2. Entscheiden Sie, ob die Schreibrouten geschlossen bleiben müssen: Sie prüfen weiterhin content/create, content/edit und content/remove, die Anonymous nicht haben darf.
3. Planen Sie die Last ein: Eine öffentliche API kann massenhaft aufgerufen werden. Setzen Sie Ratenbegrenzungen davor (Webserver oder request-shield, Sicherheitshärtung).
4. Setzen Sie RequireHTTPS in rest.ini, wenn Ihre Installation es erlaubt.
5. Leeren Sie nach der Änderung den INI-Cache (php bin/php/ezcache.php --clear-tag=ini).

Das ist eine Sicherheitsentscheidung; halten Sie fest, wer sie genehmigt hat.

Aufrufe, die ein Datenclient macht #

# the datasets of the catalog folder, 50 at a time
curl -s "https://www.example.gov/api/ezp/v2/content/node/<catalog node id>/list/offset/0/limit/50"

# the metadata of one dataset
curl -s "https://www.example.gov/api/ezp/v2/content/node/<dataset node id>/fields"

# only its license
curl -s "https://www.example.gov/api/ezp/v2/content/node/<dataset node id>/field/license"

Fügen Sie -H "Authorization: Bearer expk_..." hinzu, solange eine Authentifizierung verlangt wird.

Was sie nicht ist #

• Keine Abfrageschnittstelle über die Daten in Ihren Dateien. Die API liefert Inhaltsobjekte und ihre Felder; eine CSV-Datei ist ein Dateifeld, keine Zeilen, die Sie filtern können.
• Kein DCAT. Das JSON folgt der eigenen Struktur der API, keinem Katalogvokabular.
• Die Atom-Route listAtom antwortet mit 500 (bekanntes Problem, Abschnitt 8 der Anleitung); verwenden Sie für Feeds Setup > RSS.

Datensätze aus einem anderen System aktuell halten #

Kommen die Metadaten eines Datensatzes oder seine aktuelle Datei aus einem anderen System (einer Statistikdatenbank, einem Register), kann dieses System die Seite des Datensatzes über dieselbe API aktuell halten. Seit Exponential 6.0.15 mit ezprestapi 1.2.9 veröffentlicht ein PUT /api/ezp/v2/content/node/<Knoten-ID des Datensatzes> eine neue Version des Datensatzes mit den gesendeten Werten, sodass die Versionsgeschichte jede Änderung zeigt, wie es die Seite zur Versionierung verlangt. Eine Datei wird als öffentliche https-Adresse angegeben, die der Server herunterlädt:

curl -s -X PUT -H "Authorization: Bearer $EXP_API_KEY" -H "Content-Type: application/json" \
     -d '{"modified":"1767225600","file":"https://stats.example.gov/exports/2026-12.csv|population-2026-12.csv"}' \
     "https://www.example.gov/api/ezp/v2/content/node/<dataset node id>"

Die Attributbezeichner sind die Ihrer Datensatzklasse. Geben Sie dem System ein eigenes Konto mit content/edit nur für den Katalog und einen Schlüssel mit dem Scope edit; eine Version, die ein Freigabe-Workflow hält, wird mit 202 beantwortet. Innerhalb der Installation leistet ein zeitgesteuertes Skript dasselbe mit expContentWriter aus dem Kernel (Inhalte aus PHP schreiben).

Bevor Sie sie ankündigen #

• To do: Entscheiden Sie zwischen authentifiziert und anonym, und dokumentieren Sie, wie Clients einen Schlüssel erhalten.
• To do: Veröffentlichen Sie eine kurze Seite mit der Basisadresse, den Aufrufen oben und der Lizenz der Daten.
• To do: Beobachten Sie nach dem Start die Anfrageprotokolle und das Prüfprotokoll (Anfrageprotokolle, Prüfprotokoll).

Verwandte Seiten #

• REST-API v1 und v2
• Neu in 6.0.15: Die REST-API ändert Inhalte
• Persönliche API-Schlüssel
• Entfernte Dienste und Apps
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.