Die REST-API #

Diese Seite richtet sich an Entwickler, die eine mobile App, ein Frontend einer anderen Technologie oder ein anderes System an eine Exponential-Website anbinden. Exponential 6 liefert eine REST-Schnittstelle zum Lesen von Inhalten und zum Anlegen und Entfernen mit; diese Seite sagt Ihnen, was sie heute abdeckt, wie Sie sich authentifizieren und wo ihre Grenzen liegen.

Inhalt #

1. Was die API bedient
2. Adressen
3. Die Routen
4. Authentifizierung
5. Berechtigungen und Antworten
6. Beispiele
7. Einstellungen
8. Grenzen, die Sie kennen sollten
9. Eigene Routen

Was die API bedient #

Das REST-Rahmenwerk liegt im Kernel (kernel/private/rest/, settings/rest.ini). Die Inhaltsrouten kommen aus der Erweiterung ezprestapi (se7enxweb/ezprestapi, von der composer.json im Hauptverzeichnis verlangt), deren Provider ezp7xRestApiProvider die Präfixe ezp und ezpl bedient. Der Authentifizierungs-Provider des Kernels bedient auth, den OAuth2-Token-Endpunkt. Der ältere ezprestapiprovider ist veraltet (REST-API v1 und v2).

Adressen #

/api/ezp/v1/content/node/2
 |    |   |  |
 |    |   |  path
 |    |   version (v1 or v2)
 |    prefix (provider)
 ApiPrefix (rest.ini [System])

v1 antwortet wie immer, für vorhandene Clients; Schreibzugriffe gibt es nur in v2.

Die Routen #

Relativ zu /api/ezp/<version>:

Abfrageparameter: ResponseGroups=Metadata,Locations,Fields wählt, was eine Antwort enthält; OutputFormat=xhtml fügt in v2 die gerenderte Ausgabe der Ansicht des Knotens hinzu (Die Routen).

Authentifizierung #

rest.ini [Authentication] RequireAuthentication=enabled ist der Standard: Jede Inhaltsroute braucht einen Benutzer.

Eine Anfrage läuft immer als ein Benutzer und geht nie über dessen Richtlinien hinaus; ein Schlüssel ist zudem auf seine Scopes beschränkt. Schlüssel werden einmal angezeigt, können ablaufen und widerrufen werden (Persönliche API-Schlüssel, OAuth2-Tokens).

Berechtigungen und Antworten #

Jeder Aufruf prüft content/read, content/create oder content/remove seines Benutzers, wie es die Website tut. Antworten: 200, 201 für ein Anlegen, 400 für ein fehlendes oder unbekanntes Feld, 401 ohne gültige Zugangsdaten, 403 access_denied, wenn der Benutzer es nicht darf, 404 für einen unbekannten Knoten. Richten Sie API-Zugriff ein, indem Sie einem eigenen Konto eine Rolle mit genau den Rechten geben, die der Client braucht (Sektionen, Rollen und Richtlinien).

Beispiele #

Halten Sie den Schlüssel in einer Umgebungsvariablen, nie in einer Datei, die Sie committen:

read -s EXP_API_KEY && export EXP_API_KEY
curl -s -H "Authorization: Bearer $EXP_API_KEY" https://www.example.com/api/ezp/v1/content/node/2
curl -s -H "Authorization: Bearer $EXP_API_KEY" \
  "https://www.example.com/api/ezp/v1/content/node/2/list/offset/0/limit/20?ResponseGroups=Fields"
curl -s -H "Authorization: Bearer $EXP_API_KEY" https://www.example.com/api/ezp/v2/content/node/create \
  -d parentNodeID=<node id> -d classIdentifier=folder -d languageLocale=eng-US -d name='From a script'

Ein Anlegen antwortet mit {"message":"Created","objectId":...,"nodeId":...}. Mehr unter Beispiele mit curl und in der Lektion Die API mit einem persönlichen Schlüssel aufrufen.

Einstellungen #

Lesen Sie sie so, wie die Website sie sieht: ./console exp:ini list rest.ini/Authentication. Schalten Sie RequireHTTPS für jede Installation ein, die für andere erreichbar ist.

Grenzen, die Sie kennen sollten #

• Schreibzugriffe brauchen Exponential 6.0.15. ezprestapi 1.2.9 schreibt über expContentWriter aus dem Kernel; auf einem älteren Kernel antworten Anlegen, Aktualisieren und Löschen mit 501. Ein Aktualisieren veröffentlicht eine neue Version; Werte gehen als Formularfelder oder JSON-Body, eine Datei als öffentliche http(s)-URL (REST-API v1 und v2, Abschnitt 2.1). Die GraphQL-Mutation updateContent (Die GraphQL-API) und ein Skript auf dem Server (Inhalte aus PHP) bleiben Alternativen.
• listAtom antwortet mit 500 in v1 und v2: Verwenden Sie die Route list oder den RSS-Export der Website (Bekanntes Problem: listAtom).
• Das ist nicht die REST-API der Symfony-Plattformen. Clients, die für /api/ibexa/v2 geschrieben wurden, brauchen Änderungen (Umstieg von eZ Platform oder Ibexa).
• GraphQL ist eine eigene API. Exponential 6.0.15 antwortet mit GraphQL unter /api/graphql, aus, bis es eingeschaltet wird (Die GraphQL-API).

Eigene Routen #

Ein REST-Provider in Ihrer Erweiterung fügt Routen unter einem eigenen Präfix hinzu, mit Controllern, die die Kernel-API verwenden (Ein eigener REST-Provider). Für Funktionen der Administration und einfache JSON-Aufrufe gibt es außerdem expservices und die Serverfunktionen von ezjscore (Headless-Auslieferung).

Verwandte Seiten #

• Entfernte Dienste und Apps
• Standards für APIs und Protokolle
• Modul 11: Die REST-API
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.