Die REST-API für Integratoren #

Diese Seite richtet sich an Entwickler von Systemen, die Exponential über HTTP aufrufen. Die REST-Inhalts-API wird von der Erweiterung ezprestapi (von der composer.json im Wurzelverzeichnis als ~1.2.6 verlangt) auf dem REST-Framework des Kernels (kernel/private/rest/) bereitgestellt. Die vollständige Referenz ist REST-API v1 und v2; diese Seite wählt aus, was eine Integration braucht, und ergänzt Ratschläge für die Client-Seite.

Inhalt #

1. Was sie kann und was nicht
2. Die Routen
3. Eine große Liste seitenweise lesen
4. Anlegen und entfernen
5. Antworten, die Ihr Client behandeln muss
6. Ein kleiner Client in Python
7. Einstellungen, die das Verhalten ändern

Was sie kann und was nicht #

Lesende Aufrufe antworten unter v1 und v2, schreibende nur unter v2. Links in einer v1-Antwort bleiben in v1.

Die Routen #

Alle Pfade liegen unterhalb von /api/ezp/v1 oder /api/ezp/v2 (das Präfix ezpl ist ein Alias von ezp).

Abfrageparameter der lesenden Aufrufe: ResponseGroups=Metadata,Locations,Fields wählt die Teile der Antwort, und OutputFormat=xhtml ergänzt die gerenderte Ansicht in renderedOutput.

Eine große Liste seitenweise lesen #

Fragen Sie zuerst die Anzahl ab und gehen Sie die Liste dann mit fester Seitengröße durch. Sortieren Sie nach einem stabilen Schlüssel, damit sich die Seiten beim Lesen nicht verschieben.

export EXP_API_KEY='expk_...'
BASE=https://example.com/api/ezp/v1

curl -s -H "Authorization: Bearer $EXP_API_KEY" "$BASE/content/node/<node id>/childrenCount"
curl -s -H "Authorization: Bearer $EXP_API_KEY" \
     "$BASE/content/node/<node id>/list/offset/0/limit/50?ResponseGroups=Metadata,Fields"
curl -s -H "Authorization: Bearer $EXP_API_KEY" \
     "$BASE/content/node/<node id>/list/offset/50/limit/50?ResponseGroups=Metadata,Fields"

Aufgelistet werden nur die Kinder eines Knotens. Um einen tiefen Baum zu lesen, gehen Sie ihn Ebene für Ebene durch oder lassen Sie einen serverseitigen Export den ganzen Teilbaum in einem Lauf schreiben (Einen Export schreiben).

Anlegen und entfernen #

# create and publish a folder below a parent (v2 only)
curl -s -H "Authorization: Bearer $EXP_API_KEY" https://example.com/api/ezp/v2/content/node/create \
     -d parentNodeID=<parent node id> -d classIdentifier=folder -d languageLocale=eng-US -d name='From the ERP'
# {"message":"Created","objectId":<object id>,"nodeId":<node id>}

# remove it with all its locations and everything below them (v2 only)
curl -s -X DELETE -H "Authorization: Bearer $EXP_API_KEY" https://example.com/api/ezp/v2/content/node/delete/<node id>

Die Felder zum Anlegen sind parentNodeID, classIdentifier, languageLocale und dann die Attributbezeichner der Klasse. Das Anlegen wird als content/create dieser Klasse unterhalb dieses Elternknotens in dieser Sprache geprüft, und der Workflow für das Veröffentlichen läuft wie in der Administration. Das Backend für das Anlegen ist nxc_powercontent.

Hinweis Das Anlegen per REST hat kein Feld remote_id (der Controller liest parentNodeID, classIdentifier und languageLocale und behandelt jedes andere Feld als Attribut). Lesende Aufrufe liefern die Remote-IDs aber: Die Metadaten einer Antwort tragen objectRemoteId, bei einem Knoten nodeRemoteId. Eine Integration, die ihre Objekte wiederfinden muss, sollte die zurückgegebene objectId bei sich speichern oder Inhalte aus PHP anlegen, wo remote_id unterstützt wird (Idempotente Importe).

Antworten, die Ihr Client behandeln muss #

Ein kleiner Client in Python #

Nur mit der Standardbibliothek:

import json, os, time, urllib.error, urllib.request

BASE = 'https://example.com/api/ezp/v1'
KEY = os.environ['EXP_API_KEY']

def get(path):
    for attempt in range(5):
        request = urllib.request.Request(BASE + path, headers={'Authorization': 'Bearer ' + KEY})
        try:
            with urllib.request.urlopen(request, timeout=30) as answer:
                return json.load(answer)
        except urllib.error.HTTPError as error:
            if error.code in (429, 502, 503):
                time.sleep(int(error.headers.get('Retry-After', 2 ** attempt)))
                continue
            raise
    raise RuntimeError('gave up on ' + path)

print(get('/content/node/2')['metadata']['objectName'])

Einstellungen, die das Verhalten ändern #

settings/rest.ini, überschrieben in settings/override/rest.ini.append.php:

Leeren Sie nach einer Änderung den INI-Cache (php bin/php/ezcache.php --clear-tag=ini --allow-root-user), laden Sie PHP-FPM neu und starten Sie Velocity neu, wenn es die Website ausliefert.

Verwandte Seiten #

• REST-API v1 und v2 und Persönliche API-Schlüssel
• ezprestapi, nxc_powercontent
• Die REST-API für App-Ersteller
• Zugangsdaten für eine Integration wählen
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.