Headless Exponential #

Diese Seite richtet sich an Anwendungsentwickler, die das Inhaltsmodell, die Bearbeitung und die Rechte von Exponential ohne seine Templates nutzen möchten: für eine mobile App, eine Single-Page-Anwendung, einen Generator für statische Websites oder ein anderes System, das die Inhalte anzeigt.

Inhalt #

1. Was Sie behalten und was Sie ersetzen
2. Die API wählen
3. Inhalte lesen
4. Rich Text, Bilder und Links
5. Vorschau und Entwürfe
6. Caching und Leistung
7. Hybrid: Templates und API zusammen

Was Sie behalten und was Sie ersetzen #

Die API wählen #

Ein Frontend, das im Browser auf einem anderen Host läuft, ruft die REST-API erst auf, wenn CORS für seinen Ursprung in rest.ini [CorsSettings] eingeschaltet ist; standardmäßig ist es aus (CORS für die REST-API). Eine Browser- oder mobile App, bei der sich Benutzer anmelden, ist ein öffentlicher OAuth-Client und verwendet PKCE (PKCE und state).

Inhalte lesen #

curl -s -H "Authorization: Bearer $EXP_API_KEY" \
     "https://example.com/api/ezp/v2/content/node/<node id>/list/offset/0/limit/20?ResponseGroups=Metadata,Fields"

Öffentliche Inhalte können anonymen API-Benutzern nur ausgeliefert werden, wenn rest.ini [Authentication] RequireAuthentication das erlaubt; standardmäßig ist ein Benutzer erforderlich. Für öffentliche Frontends verwenden Sie einen Integrationsbenutzer mit reinen Leserechten und behalten seinen Schlüssel auf Ihrem Server.

Rich Text, Bilder und Links #

• Jedes REST-Feld hat type, identifier, value, id und classattribute_id. Der value eines Rich-Text-Felds ist reiner Text: seine gerenderte Ausgabe ohne Tags.

• OutputFormat=xhtml ergänzt renderedOutput: den ganzen Knoten, von Templates gerendert, im View-Modus rest, innerhalb des Templates aus rest.ini [<Controller>_viewContent_OutputSettings] Template (rest_pagelayout.tpl). Das mitgelieferte rest_pagelayout.tpl ist nur eine Platzhalterseite; überschreiben Sie es in Ihrem Design und ergänzen Sie ein node/view/rest.tpl, um brauchbares Markup zu erhalten.

• Bilder: Der REST-value eines Bildfelds ist nur der Pfad der Originaldatei, relativ zum Wurzelverzeichnis der Website (zum Beispiel var/<site>/storage/images/.../name.jpg); er enthält keine Bildvarianten, keine Größe und keinen Alternativtext. Adressen der Bildvarianten erhalten Sie heute so:

  • über die Bilddomäne von expservices, ezjscore/call/expimage::url::<Knoten-ID>::<Attribut>::<Variante> für eine Variante (die Datei wird erzeugt, wenn sie fehlt) oder expimage::urls::<Knoten-ID>::<Attribut> für alle konfigurierten Varianten, jeweils mit url, absolute_url, Breite, Höhe und MIME-Typ (Entfernte Dienste mit expservices); oder
  • indem Sie sie in Ihr rest-View-Template schreiben ($node.data_map.<Attribut>.content.<Variante>.url) und renderedOutput lesen.

  Definieren Sie Bildvarianten für die Größen Ihres Frontends in image.ini (Bilder und Bildvarianten).

• Links im Rich Text zeigen auf Adressen der Website; bilden Sie sie per URL-Alias oder Knoten-ID auf die Routen Ihres Frontends ab.

Vorschau und Entwürfe #

Die Redaktion sieht die Vorschau in der Administration mit den Templates der Website. Ein Headless-Frontend braucht eine eigene Vorschau: Lesen Sie die Entwurfsversion über einen authentifizierten Aufruf mit Redakteursrechten und rendern Sie sie in einer geschützten Vorschau-Route. Planen Sie das früh ein; diesen Teil vergessen Teams am häufigsten.

Caching und Leistung #

• Das REST-Framework hat einen Antwort-Cache (rest.ini); die rest-Caches werden mit dem Tag content geleert.
• Cachen Sie in Ihrem Frontend oder CDN; leeren Sie beim Veröffentlichen mit einem Workflow-Ereignis oder einem Listener, der Ihren Purge-Hook aufruft (Workflows und Ereignisse).
• Holen Sie Listen seitenweise mit Limits.

Hybrid: Templates und API zusammen #

Viele Projekte behalten die Website in Templates und ergänzen eine App über die API. So bleiben Vorschau, Layouts und SEO für die Website einfach, und die App erhält dieselben Inhalte. Beginnen Sie hybrid, sofern nichts dagegen spricht.

Verwandte Seiten #

• Die REST-API
• OAuth und API-Schlüssel
• Standard für APIs und Protokolle
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.