Inhalte anlegen und entfernen #

Diese Seite richtet sich an App-Entwickler, deren App Inhalte hinzufügt oder ändert: einen Bericht aus dem Außeneinsatz, eine Einsendung eines Benutzers, einen von einem Gerät importierten Eintrag. Sie erklärt die Schreibrouten der REST-API (Anlegen, Aktualisieren, Entfernen), die nur unter v2 antworten. Das Aktualisieren braucht ezprestapi 1.2.9, das über den Kernel von Exponential 6.0.15 schreibt; auf einem älteren Kernel antworten seine Schreibrouten mit 501.

Inhalt #

1. Anlegen und veröffentlichen
2. Wie Sie den Body senden
3. Entfernen
4. Aktualisieren
5. Berechtigungen und Scopes
6. Ratschläge für das Design schreibender Apps

Anlegen und veröffentlichen #

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 a script'

{"message":"Created","objectId":<object id>,"nodeId":<node id>}

Die Antwort ist 201 mit objectId und nodeId (dem neuen Hauptknoten). Das Element wird sofort veröffentlicht: Der Controller legt es über expContentWriter aus dem Kernel an, und „ein Anlegen veröffentlicht, wenn content/create es erlaubt, und der Veröffentlichungs-Workflow läuft wie beim Content-Modul“ (Berechtigungen der REST-Schnittstelle).

Feldwerte sind Zeichenketten. Ein Rich-Text-Feld wird vom Eingabeparser des Online-Editors verarbeitet und nimmt daher einfaches HTML wie <p>Text</p> an; Links und Einbettungen werden zu Beziehungen. Ein Bild- oder Dateifeld (ezimage, ezbinaryfile, ezmedia) nimmt eine öffentliche http(s)-URL oder <URL>|<Alternativtext oder Dateiname> an, die der Server herunterlädt: Ein Serverpfad, file://, Zugangsdaten in der URL und Adressen in privaten, Loopback-, Link-Local- oder reservierten Netzen werden abgewiesen, Weiterleitungen werden nicht verfolgt, und eine Datei darf höchstens 50 MB groß sein. Keine Route nimmt eine Datei direkt vom Gerät entgegen (Dateien und Uploads). Jedes andere Feld nimmt seine Textform an.

Wie Sie den Body senden #

Senden Sie die Felder formularkodiert (application/x-www-form-urlencoded, wie es curl -d tut, oder multipart/form-data) oder als JSON-Objekt mit Content-Type: application/json (ezprestapi 1.2.9). Anlegen und Aktualisieren lesen beides. Im App-Code:

// Kotlin, OkHttp
val body = FormBody.Builder()
    .add("parentNodeID", parentId.toString())
    .add("classIdentifier", "article")
    .add("languageLocale", "eng-US")
    .add("title", title)
    .build()

// Swift: percent-encode each value before joining
request.httpMethod = "POST"
request.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
request.httpBody = "parentNodeID=\(parentId)&classIdentifier=article&languageLocale=eng-US&title=\(encodedTitle)"
    .data(using: .utf8)

Entfernen #

curl -s -X DELETE -H "Authorization: Bearer $EXP_API_KEY" https://example.com/api/ezp/v2/content/node/delete/<node id>

{"message":"Removed","nodeId":<node id>,"objectId":<object id>}

Das entfernt das Objekt des Knotens mit allen seinen Platzierungen und allem, was darunter liegt. Ein POST an denselben Pfad funktioniert ebenfalls, ebenso ein POST mit dem Formularfeld _method=DELETE, das der Request-Parser für Clients, die kein DELETE senden können, in ein DELETE umwandelt. Lassen Sie den Benutzer in der App bestätigen; es gibt keine Route zum Rückgängigmachen.

Aktualisieren #

curl -s -X PUT -H "Authorization: Bearer $EXP_API_KEY" -H 'Content-Type: application/json' \
     https://example.com/api/ezp/v2/content/node/<node id> -d '{"name": "New title", "intro": "<p>New intro</p>"}'

{"message":"Updated","objectId":<object id>,"nodeId":<node id>,"version":<version>,"languageLocale":"eng-US"}

POST oder PUT auf /api/ezp/v2/content/node/<id> (oder ein POST mit _method=PUT) veröffentlicht eine neue Version des Objekts des Knotens mit den gesendeten Feldern; nicht gesendete Felder behalten ihre Werte. languageLocale ist optional, Standard ist die Hauptsprache des Objekts; eine Sprache, die das Objekt noch nicht hat, fügt diese Übersetzung hinzu. Die neue Version durchläuft die Veröffentlichungsoperation, Workflows laufen also: Hält einer die Veröffentlichung zurück, lautet die Antwort 202 mit „Waiting for a workflow“. Für die Werte gelten dieselben Regeln wie beim Anlegen. Ein 400 bedeutet keine Werte, ein unbekanntes Feld, einen Wert, der kein Text ist, einen Dateiwert, der keine öffentliche http(s)-URL ist, oder eine unbekannte Sprache.

Auf einem Server älter als Exponential 6.0.15 antwortet die Route mit 501 und not_implemented; ändern Sie ein Element dort mit expnode::update der Remote-Dienste (Über expservices schreiben).

Berechtigungen und Scopes #

Eine Ablehnung antwortet mit 403 und access_denied sowie einer Meldung wie „You may not create 'article' below node 60 in eng-US (content/create).“ und ändert nichts (Leitfaden zu API-Schlüsseln, 3.2).

Ratschläge für das Design schreibender Apps #

• Legen Sie Inhalte unterhalb eines Ordners pro App an und geben Sie den Benutzern der App content/create nur dort und nur für die Klassen, die sie brauchen (Berechtigungen für App-Benutzer).
• Machen Sie das Anlegen in der App idempotent. Ein Anlegen, das in eine Zeitüberschreitung lief, kann erfolgreich gewesen sein; prüfen Sie vor einem erneuten Versuch, ob das Element existiert, zum Beispiel über einen eindeutigen Titel oder indem Sie den Ordner nach published sortiert auflisten.
• Stellen Sie offline vorgenommene Schreibzugriffe in eine Warteschlange und senden Sie sie nacheinander, sobald das Gerät wieder online ist (Synchronisieren und Offline-Lesen).
• Zeigen Sie dem Benutzer die Meldung des Servers bei einem 400 oder 403; sie nennt, was fehlt oder abgelehnt wurde.

Verwandte Seiten #

• Fehler und Statuscodes
• REST-API v1 und v2: Beispiele mit curl
• Inhalte im Code anlegen
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.