API-Design: REST, ezjscore und Headless #

Diese Seite richtet sich an Ingenieure, die Exponential mit anderen Systemen verbinden, ein Frontend darauf bauen oder eigene Endpunkte hinzufügen. Der Stand jedes Protokolls, mit Belegen und Lücken, steht in Standards für APIs und Protokolle.

Inhalt #

1. Die Schnittstellen
2. Die REST-Inhalts-API
3. Die ezjscore-Aufrufschnittstelle
4. Ausgehende Ereignisse
5. Headless und hybrid
6. Einen eigenen Endpunkt entwerfen
7. Bekannte Lücken

Die Schnittstellen #

Die REST-Inhalts-API #

• Eine Erweiterung, ezprestapi, bedient /api/ezp/v1/... und /api/ezp/v2/...: Lesen in beiden Versionen, Schreiben (Erstellen, Aktualisieren, Löschen) nur in v2. ezprestapiprovider ist abgekündigt.
• Authentifizierung: ein OAuth-2.0-Token von POST /api/auth/v1/oauth/token oder ein persönlicher API-Schlüssel als Authorization: Bearer expk_....
• Jedes Lesen und Schreiben prüft die Richtlinien des Benutzers (content/read, content/create, content/edit, content/remove), was auch immer die Anfrage authentifiziert hat.
• Ein API-Schlüssel über seinem Ratenlimit erhält 429 Too Many Requests mit Retry-After.
• Einstellungen: settings/rest.ini.

Anleitung mit curl-Beispielen: REST-API v1 und v2. Für Autoren: REST-API, für Anwendungsentwickler.

Die ezjscore-Aufrufschnittstelle #

/ezjscore/call/<class>::<method> ruft eine registrierte Serverfunktion auf und antwortet mit JSON. Serverfunktionen sind PHP-Klassen, die in ezjscore.ini registriert und durch Rollenrichtlinien geschützt sind. Verwenden Sie sie für das JavaScript Ihrer eigenen Seiten und für kleine App-Aufrufe (JSON-Endpunkte mit ezjscore, Backend-Dienste von ezjscore, Referenz der ezjscore-Serverfunktionen).

Ausgehende Ereignisse #

Nur das Audit-Log sendet Webhooks: Stapel von Datensätzen als JSON mit Zeitstempel und HMAC-SHA-256-Signatur, über einen Spool mit Wiederholungen zugestellt, mindestens einmal und nach Ereignis-ID dedupliziert (settings/audit.ini [AuditSink_webhook], aus, bis eine URL gesetzt ist). Inhaltsereignisse (Veröffentlichen, Entfernen) haben keinen allgemeinen ausgehenden Webhook; um darauf zu reagieren, verwenden Sie ein Workflow-Ereignis oder einen Listener in einer Erweiterung (Events, Erweiterungspunkte und Plugins).

Headless und hybrid #

Sie behalten Inhaltsklassen, Bearbeitung, Versionen, Übersetzungen, Workflows und Berechtigungen; das Frontend ersetzt Seiten-Templates, Menüs und Routing. Planen Sie ein:

• Lesen über die REST-API, mit den Berechtigungen des authentifizierten Benutzers;
• Rich Text und Bilder: gerendertes XHTML und Bildvarianten, mit ihren URLs ausgeliefert;
• Vorschau von Entwürfen für Redakteure;
• Caching: die eigenen Cache-Einstellungen der API und ein HTTP-Cache davor für öffentliche Lesezugriffe;
• hybrid: Templates für einige Seiten, die API für Apps, auf denselben Inhalten.

Details: Headless Exponential.

Einen eigenen Endpunkt entwerfen #

• Wählen Sie den Ort: eine REST-Route in einer Erweiterung für Ressourcen, eine ezjscore-Serverfunktion für kleine Aufrufe aus Ihren eigenen Seiten, eine Modul-View für HTML.
• Entscheiden Sie Berechtigungen mit Richtlinienfunktionen, nie mit Benutzer-IDs; prüfen Sie sie bei jedem Aufruf.
• Nehmen Sie Zustandsänderungen nur per POST (oder PUT, PATCH, DELETE) an, mit einem Formular-Token für Browser-Aufrufe oder einem Token oder Schlüssel für Maschinen.
• Geben Sie JSON mit json_encode() zurück; geben Sie Fehlern einen Statuscode und ein stabiles maschinenlesbares Feld.
• Halten Sie die Form stabil: Ein entferntes oder umbenanntes Feld ist ein Bruch, der Upgrade-Hinweise braucht (Richtlinie zur Rückwärtskompatibilität).
• Versionieren Sie den Pfad, wenn sich die Form ändern muss, wie ezprestapi es mit v1 und v2 tut.
• Protokollieren und auditieren Sie Schreibzugriffe; protokollieren Sie nie Tokens oder Schlüssel.

Bekannte Lücken #

Laut Standard: keine OpenAPI-Beschreibung der REST-API des Kernels (Velocity veröffentlicht eine nur für seine eigenen Handler), kein JSON:API, keine bedingten Anfragen bei Schreibzugriffen gefunden, keine allgemeinen Inhalts-Webhooks, kein Endpunkt für eingehende Webhooks, und dem OAuth-Server fehlt PKCE.

Verwandte Seiten #

• OAuth und API-Schlüssel
• Entfernte Dienste mit expservices
• AJAX mit ezjscore-Serverfunktionen
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.