REST API im Jitterbit App Builder

Einführung

REST ist ein architektonischer Stil für Webdienste. REST definiert eine Reihe von zustandslosen Operationen, die auf Ressourcen ausgeführt werden können. Der App Builder ermöglicht es Entwicklern, Datenobjekte als REST-Ressourcen zu veröffentlichen. Verbraucher können Operationen auf diesen Ressourcen durchführen, die in Datenobjekt-Ereignisaufrufe übersetzt werden.

Anwendungen als Webdienste

Die Designumgebung des App Builders ist um das Konzept einer Anwendung organisiert. Obwohl Anwendungen typischerweise eine Benutzeroberfläche beschreiben, haben Anwendungen mehrere Eigenschaften, die auch für Webdienste gelten:

Anwendungen bieten Zugriff auf mehrere Datenquellen.
Gruppen wird das Privileg für eine Anwendung gewährt.

Der App Builder erweitert das Konzept einer Anwendung um Webdienste. Insbesondere haben Entwickler die Möglichkeit, einen Endpunkt für eine Anwendung zu definieren. Zum Beispiel könnte der Endpunkt für die Verkaufsanwendung "sales" sein. Die entsprechende URI könnte folgendermaßen aussehen:

https://example.com/Vinyl/rest/v1/sales

Datenobjekte als Ressourcen

Das organisierende Prinzip von REST ist das Konzept einer "Ressource". Ressourcen können eine Sammlung von Elementen oder ein einzelnes Element darstellen. In den Begriffen des App Builders wird ein Datenobjekt als Sammlung dargestellt, wobei einzelne Zeilen als Elemente in dieser Sammlung repräsentiert werden.

Wie der Dienst selbst bestimmt der Entwickler den Endpunkt des Datenobjekts. Zum Beispiel könnte das Datenobjekt "Kunden" einen Endpunkt von "customers" haben. In diesem Fall könnte die entsprechende URI folgendermaßen aussehen:

https://example.com/Vinyl/rest/v1/sales/customers

Die URI für ein bestimmtes Element (Zeile) könnte folgendermaßen aussehen:

https://example.com/Vinyl/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1

Der Primärschlüssel erscheint im URI-Pfad.

Zusammengesetzte Primärschlüssel können angegeben werden, indem die Schlüssel durch ein Komma getrennt werden:

https://example.com/Vinyl/rest/v1/sales/customers/abc,def

Ereignisse als HTTP-Methoden

REST definiert eine Reihe von Operationen, die den HTTP-Methoden entsprechen. Die REST-API von App Builder unterstützt die folgenden HTTP-Methoden:

GET /collection: Ruft die Elemente innerhalb einer Sammlung ab. Dies entspricht dem Filterereignis.
POST /collection: Fügt ein Element zur Sammlung hinzu. Dies entspricht dem Einfügeereignis.
GET /collection/item: Ruft ein einzelnes Element aus der Sammlung ab. Dies entspricht dem Filterereignis.
POST /collection/item: Aktualisiert ein Element in der Sammlung. Dies entspricht dem Aktualisierungsereignis.
DELETE /collection/item: Löscht ein Element aus der Sammlung. Dies entspricht dem Löschereignis.

Die REST-API von App Builder unterstützt derzeit nicht die folgenden HTTP-Methoden:

HEAD: Die HEAD-Methode ermöglicht es den Verbrauchern, die HTTP-Antwortheader abzurufen. Momentan unterstützt App Builder diese Operation nicht.
OPTIONS: Die OPTIONS-Methode ermöglicht es den Verbrauchern zu bestimmen, welche Methoden unterstützt werden.
PUT (Sammlung oder Element): Die PUT-Methode ermöglicht es den Verbrauchern, ein Element zu erstellen (wenn die Sammlung adressiert wird) oder ein Element zu aktualisieren (wenn das Element adressiert wird). Da PUT jedoch idempotent ist, müssen alle Felder enthalten sein. Dies schränkt die Nützlichkeit in vielen Szenarien ein.
PATCH: Die PATCH-Methode ermöglicht es den Verbrauchern, einen Teil eines Elements zu aktualisieren. Dies wird derzeit über ein POST unterstützt. Typischerweise verwendet PATCH ein patch-spezifisches Format, was die Implementierung kompliziert.

Nicht alle Ereignisse von App Builder können veröffentlicht werden:

Neu: Das Neue Ereignis von App Builder erstellt eine nicht persistente Zeile und wendet alle Standardwerte an. Verbraucher können das Neue Ereignis nicht aufrufen.
Änderung: Interaktionen mit der Benutzeroberfläche lösen ein Pseudoereignis aus, das Standardwerte und Validierungen ausführt, ohne Änderungen zu speichern. Verbraucher können das Änderungsereignis nicht simulieren.
Benutzerdefinierte Ereignisse: Neben den intrinsischen Ereignissen können Entwickler ihre eigenen Ereignisse definieren. Derzeit können diese nicht auf Ressourcenmethoden abgebildet werden.

RESTful Designprinzipien

Soweit möglich, folgt die REST-API von App Builder diesen RESTful Prinzipien:

Dienste sind zustandslos.
Endpunkte werden als Ressourcen modelliert.
GET-Operationen sind sicher. Eine "sichere" Operation hat keine Nebenwirkungen. Zum Beispiel ändert das Abrufen einer Liste von Kunden nicht die Liste der Kunden.
DELETE-Operationen sind unsicher, aber idempotent. Während die erste (erfolgreiche) Anfrage zum Löschen eines Elements einen Statuscode von 200 zurückgibt, wird die zweite Anfrage einen 404 zurückgeben.
POST-Operationen sind weder sicher noch idempotent. Aus diesem Grund können POST-Operationen teilweise Daten enthalten.
HTTP-Statuscodes zeigen an, ob ein Fehler aufgetreten ist.
Medientypen werden verwendet, um eine Inhaltsverhandlung durchzuführen. Im Moment unterstützt App Builder jedoch nur JSON (application/json) und UTF-8.

App Builder hält sich nicht an alle RESTful-Prinzipien:

Ressourcenantworten sind in einem Umschlag verpackt. Dies ermöglicht es App Builder, zusätzliche Informationen wie Ereignisnachrichten und Validierungsergebnisse einzuschließen.
Ressourcenantworten sind kein Hypermedia: Sie enthalten keine Links zu anderen Ressourcen.

REST-URI-Konventionen

Auf der Sammlungsebene unterstützt die GET-Methode die folgenden Funktionen:

Paging über die Parameter $offset und $limit. Das Standardlimit beträgt 10; das maximale Limit beträgt 100.
Sortierung über einen $sort-Parameter. Der $sort-Parameter kann eine durch Kommas getrennte Liste von Feldnamen annehmen. Präfixieren Sie den Feldnamen mit einem Minuszeichen (-), um das Feld in absteigender Reihenfolge zu sortieren. Zum Beispiel würde die Sortierspezifikation $sort=-country,companyName die Sammlung nach Land, absteigend, und companyName, aufsteigend, sortieren.
Auswahl über einen $fields-Parameter. Der $fields-Parameter kann eine durch Kommas getrennte Liste von Feldnamen annehmen (z. B. $fields=customerId,country). Geben Sie das Sternchen (*) an, um alle Ressourcenfelder abzurufen (z. B. $fields=*).
Suche nach Schlüsselwörtern über einen $q-Parameter. Der $q-Parameter nimmt einen String entgegen und versucht, mit Spaltenwerten übereinzustimmen. Alle Tabellenzeilen, die mindestens einen Spaltenwert haben, der den $q-Parameter als Teilzeichenfolge enthält, werden zurückgegeben (z. B. $q=miami). Beachten Sie, dass die Übereinstimmung nicht zwischen Groß- und Kleinschreibung unterscheidet.
Filtern über einfache Gleichheitsvergleiche. Um die Ergebnisse einzuschränken, geben Sie den Feldnamen und den Wert an (z. B. countryId=USA).
Zählen über den Parameter $count. Standardmäßig gibt der App Builder keine Gesamtanzahl der Elemente innerhalb der Sammlung zurück. Um die Anzahl einzuschließen, fügen Sie den Zählerparameter hinzu (z. B. $count=true).

Konventionen für Parameter:

Parameter, die sich auf Ressourcenfelder beziehen, haben kein Präfix.
Parameter, die auf die Sammlung selbst wirken, sind mit einem Dollarzeichen ($) präfixiert.

Validierung

Ein Ereignis kann ein oder mehrere Fehler, Warnungen oder informative Validierungsergebnisse als Teil der Antwort zurückgeben. Jede Validierung enthält eine validationId, eine Nachricht (definiert in der IDE) und die Schwere der Validierung ("Fehler", "Warnung", "Information").

Wenn Sie eine Warnung umgehen möchten, fügen Sie die bereitgestellten validationIds als Wert eines X-Vinyl-Ignore-Warnings-Headers in einer neuen Anfrage an den Endpunkt hinzu.

Zum Beispiel, für die folgende Antwort:

{
  "item": {
    "contactId": "8d20b593-aa41-4bbb-8bee-58f17ac2bf32",
    "name": "Company Name"
  },
  "message": null,
  "validations": [
    {
      "validationId": "8d20b593-aa41-4bbb-8bee-58f17ac2bf32",
      "message": "32 emails will be sent, are you sure?",
      "severity": "warning"
    },
    {
      "validationId": "6bad40b7-2504-4243-9e90-100bcc7bfd13",
      "message": "No subject was provided, use default?",
      "severity": "warning"
    }
  ],
  "status": 400
}

Müsste eine neue Anfrage (an denselben Endpunkt und dieselben Daten) die folgenden Headerinformationen enthalten:

X-Vinyl-Ignore-Warnings: "8d20b593-aa41-4bbb-8bee-58f17ac2bf32","6bad40b7-2504-4243-9e90-100bcc7bfd13"

Verarbeitung von POST-Antworten

Es gibt zwei Möglichkeiten, die von einem POST-Aufruf zurückgegebenen Daten zu erfassen und zu verarbeiten: Binding mit XP CRUD-Regeln oder Verwendung eines Erfolgshandlers.

Binding mit XP CRUD-Regeln

Verwenden Sie dies, wenn der POST-Aufruf Teil einer CRUD-Operation ist, bei der die Datenquelle eine externe API und das Ziel eine lokale Datenbank ist, die vom App Builder verwaltet wird.

Kontext: Wenn die Antwort eines externen API-POST-Aufrufs in eine lokale Datenbank eingefügt werden muss.
Konfiguration:
- Registrieren Sie eine XP CRUD-Regel für eine Aktion innerhalb des App Builders.
- Übergeben Sie die erforderlichen Parameter für den POST-Aufruf und ordnen Sie sie den entsprechenden Feldern in Ihrer externen API zu.
Zugriff auf Antwortdaten:
- Nach erfolgreicher Ausführung des POST wird die Antwortdaten des API in automatisch generierten Antworttabellen im App Builder zugänglich.
- Innerhalb Ihrer Regel können Sie diese Antworttabellen mit den systemgenerierten Feldern id und parent_id verknüpfen.
Verarbeitung: Verwenden Sie die XP CRUD-Funktionalität, um Felder aus diesen Antworttabellen direkt auf Spalten in Ihrer lokalen Datenbank für die Einfügung oder Aktualisierung abzubilden.

Verwendung eines Erfolgshandlers

Die Verwendung eines Erfolgshandlers bietet größere Flexibilität bei der Verarbeitung von API-Antworten mit benutzerdefinierter Logik, die möglicherweise keine direkte Datenbankzuordnung erfordert.

Implementierung:
- Fügen Sie einen Erfolgshandler an die Aktion an, die den POST-Aufruf initiiert.
- Rufen Sie die API-Antwortdaten innerhalb des Erfolgshandlers mit der caller()-Funktion ab.
Verarbeitung: Implementieren Sie benutzerdefinierte Logik innerhalb des Erfolgshandlers, um die Antwortdaten gemäß den Anforderungen Ihrer Anwendung zu analysieren, zu manipulieren oder weiterzuleiten.

Bekannte Probleme und Einschränkungen

Binäre Felder wie Dateien werden derzeit nicht unterstützt.
Der einzige unterstützte Inhaltstyp ist JSON (application/json).
Die einzige unterstützte Textkodierung ist UTF-8.
Sammlungen sind auf die Rückgabe von 100 Elementen gleichzeitig beschränkt.
Zusammengesetzte Primärschlüssel dürfen keine Kommas enthalten.
Es wird nur das Filtern über einfache Gleichheitsvergleiche unterstützt.