REST-APIs in Jitterbit App Builder

Einführung

App Builder bietet zwei primäre Möglichkeiten zur Integration mit REST-APIs:

• Externe REST-APIs nutzen (mit manueller Konfiguration oder durch Import eines OpenAPI-Dokuments), um Daten in deine Anwendungen zu bringen, oder
• Die Daten deiner App Builder-Anwendung als REST-API veröffentlichen, damit andere Systeme diese nutzen können.

Konzepte und Prinzipien

Anwendungen als Webservices

Die App Builder-Designumgebung ist um das Konzept einer Anwendung organisiert. Obwohl Anwendungen typischerweise eine Benutzeroberfläche beschreiben, haben Anwendungen mehrere Eigenschaften, die auch auf Webservices anwendbar sind:

• Anwendungen bieten Zugriff auf mehrere Datenquellen.

• Gruppen erhalten Berechtigungen für eine Anwendung.

App Builder erweitert das Konzept einer Anwendung um Webservices. Konkret haben Entwickler die Möglichkeit, einen Endpunkt für eine Anwendung zu definieren. Beispielsweise könnte der Endpunkt für eine Sales-Anwendung sales sein. Die entsprechende URI könnte so aussehen:

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

Datenobjekte als Ressourcen

Das Organisationsprinzip von REST ist das Konzept einer Ressource. Ressourcen können eine Sammlung von Elementen oder ein einzelnes Element darstellen. In App Builder-Begriffen wird ein Datenobjekt als Sammlung dargestellt, wobei einzelne Zeilen als Elemente in dieser Sammlung dargestellt werden.

Wie der Service selbst bestimmt der Entwickler den Datenobjekt-Endpunkt. Beispielsweise könnte das Datenobjekt Customers einen Endpunkt von customers haben. In diesem Fall könnte die entsprechende URI so aussehen:

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

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

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

Der Primärschlüssel wird im URI-Pfad angezeigt.

Zusammengesetzte Primärschlüssel können durch Trennung der Schlüssel mit einem Komma angegeben werden:

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

Ereignisse als HTTP-Methoden

REST definiert eine Reihe von Operationen, die 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 wird dem Ereignis Filter zugeordnet.

• POST /collection: Fügt ein Element zur Sammlung hinzu. Dies wird dem Ereignis Insert zugeordnet.

• GET /collection/item: Ruft ein einzelnes Element aus der Sammlung ab. Dies wird dem Ereignis Filter zugeordnet.

• POST /collection/item: Aktualisiert ein Element in der Sammlung. Dies wird dem Ereignis Update zugeordnet.

• DELETE /collection/item: Löscht ein Element aus der Sammlung. Dies wird dem Ereignis Delete zugeordnet.

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

• HEAD: Die HEAD-Methode ermöglicht es Consumern, die HTTP-Antwortheader abzurufen. Derzeit unterstützt App Builder diese Operation nicht.

• OPTIONS: Die OPTIONS-Methode ermöglicht es Consumern, zu bestimmen, welche Methoden unterstützt werden.

• PUT (Sammlung oder Element): Die PUT-Methode ermöglicht es Consumern, ein Element zu erstellen (bei Adressierung der Sammlung) oder ein Element zu aktualisieren (bei Adressierung des Elements). Da PUT jedoch idempotent ist, muss es alle Felder enthalten. Dies schränkt seine Nützlichkeit in vielen Szenarien ein.

• PATCH: Die PATCH-Methode ermöglicht es Consumern, einen Teil eines Elements zu aktualisieren. Dies wird derzeit über einen POST unterstützt. Typischerweise verwendet PATCH ein patch-spezifisches Format, was die Implementierung verkompliziert.

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

• New: Das Ereignis New von App Builder erstellt eine nicht persistente Zeile und wendet alle Standardwerte an. Consumer können das Ereignis New nicht aufrufen.

• Change: Interaktionen mit der Benutzeroberfläche rufen ein Pseudo-Event auf, das Standards und Validierungen ausführt, ohne Änderungen zu speichern. Nutzer können das Change-Event nicht simulieren.

• Benutzerdefinierte Events: Zusätzlich zu den intrinsischen Events können Entwickler ihre eigenen Events definieren. Diese können nicht den Standard-Ressourcenmethoden oben zugeordnet werden, können aber direkt über ein dediziertes URL-Muster aufgerufen werden. Weitere Informationen finden Sie unter Benutzerdefinierte Events aufrufen unten.

Benutzerdefinierte Events aufrufen

Zusätzlich zu den Standard-Events, die oben HTTP-Methoden zugeordnet sind, kann die REST-API von App Builder ein benutzerdefiniertes Event aufrufen, das auf einem Geschäftsobjekt definiert ist. Dies führt das Ziel-Event und alle damit verbundenen Aktionen aus, wie CRUD-Operationen, Benachrichtigungen, gespeicherte Prozeduren sowie Geschäftsregeln oder Validierungen.

Um ein benutzerdefiniertes Event aufzurufen, senden Sie eine POST-Anfrage mit der folgenden Syntax:

POST /{Resource}({EventName})/{RecordID}

Beispielsweise verwendet das Aufrufen eines Events namens SendWelcomeEmail auf einem Kundendatensatz einen URI wie diesen:

https://example.com/Vinyl/rest/v1/sales/customers(SendWelcomeEmail)/9ce33474-8690-4a75-ab90-65caa6c3c24e

RESTful-Designprinzipien

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

• Services sind zustandslos.

• Endpunkte werden als Ressourcen modelliert.

• GET-Operationen sind sicher. Eine „sichere" Operation ist eine, die keine Nebenwirkungen hat. Beispielsweise ändert das Abrufen einer Kundenliste nicht die Kundenliste.

• DELETE-Operationen sind unsicher, aber idempotent. Während die erste (erfolgreiche) Anfrage zum Löschen eines Elements einen 200-Statuscode zurückgibt, gibt die zweite Anfrage einen 404 zurück.

• POST-Operationen sind weder sicher noch idempotent. Aus diesem Grund können POST-Operationen Teildaten enthalten.

• HTTP-Statuscodes geben an, ob ein Fehler aufgetreten ist.

• Medientypen werden zur Inhaltsaushandlung verwendet. Derzeit unterstützt App Builder jedoch nur JSON (application/json) und UTF-8.

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

• Ressourcenreaktionen werden in einen Umschlag eingewickelt. Dies ermöglicht es App Builder, zusätzliche Informationen wie Event-Meldungen und Validierungsergebnisse einzubeziehen.

• Ressourcenreaktionen sind keine Hypermedia: Sie enthalten keine Links zu anderen Ressourcen.

REST-URI-Konventionen

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

• Paginierung über $offset- und $limit-Parameter. Das Standardlimit ist 10; das maximale Limit ist 100.

• Sortierung über einen $sort-Parameter. Der $sort-Parameter kann eine kommagetrennte Liste von Feldnamen annehmen. Stellen Sie dem Feldnamen einen Bindestrich (-) voran, um das Feld in absteigender Reihenfolge zu sortieren. Beispielsweise würde die Sortierspezifikation $sort=-country,companyName die Sammlung nach country (absteigend) und companyName (aufsteigend) sortieren.

• Auswahl über einen $fields-Parameter. Der $fields-Parameter kann eine kommagetrennte Liste von Feldnamen annehmen (z. B. $fields=customerId,country). Verwenden Sie ein Sternchen (*), um alle Ressourcenfelder abzurufen (z. B. $fields=*).

• Suche nach Schlüsselwort über einen $q-Parameter. Der $q-Parameter nimmt eine Zeichenkette auf und versucht, sie mit Spaltenwerten abzugleichen. Alle Tabellenzeilen, die mindestens einen Spaltenwert enthalten, der den $q-Parameter als Teilzeichenkette enthält, werden zurückgegeben (z. B. $q=miami). Der Abgleich wird ohne Beachtung der Groß-/Kleinschreibung durchgeführt.

• Filterung über einfache Gleichheitsvergleiche. Um die Ergebnisse einzugrenzen, geben Sie den Feldnamen und den Wert an (z. B. countryId=USA).

• Zählung über den Parameter $count. Standardmäßig gibt App Builder keine Gesamtanzahl der Elemente in der Sammlung zurück. Um die Anzahl einzubeziehen, fügen Sie den Count-Parameter an (z. B. $count=true).

Konventionen für Parameter:

• Parameter, die sich auf Ressourcenfelder beziehen, haben kein Präfix.

• Parameter, die auf die Sammlung selbst angewendet werden, haben ein Dollarzeichen ($) als Präfix.

Validierung

Ein Ereignis kann als Teil der Antwort ein oder mehrere Fehler, Warnungen oder Informationsvalidierungsergebnisse zurückgeben. Jede Validierung enthält eine validationId, eine message (in der IDE definiert) und den severity der Validierung (error, warning, information).

Um eine Warnung zu umgehen, fügen Sie die bereitgestellten validationIds als Wert eines X-Vinyl-Ignore-Warnings-Headers in eine neue Anfrage an den Endpunkt ein. Betrachten Sie die folgende Beispielantwort:

{
  "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
}

Um die Warnung in dieser Antwort zu umgehen, müsste eine neue Anfrage (an denselben Endpunkt und mit denselben Daten) die folgenden Header-Informationen enthalten:

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

POST-Antworten verarbeiten

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

Bindung mit XP CRUD-Regeln

Verwenden Sie dies, wenn der POST-Aufruf Teil eines CRUD-Vorgangs ist, bei dem die Datenquelle eine externe API und das Ziel eine von App Builder verwaltete lokale Datenbank ist.

• Kontext: Wenn die Antwort eines POST-Aufrufs einer externen API in eine lokale Datenbank eingefügt werden muss.

• Konfiguration:

  • Registrieren Sie eine XP CRUD-Regel für eine Aktion in App Builder.

  • Ü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 POST-Ausführung werden die Antwortdaten der API in automatisch generierten Antworttabellen in App Builder zugänglich.

  • Innerhalb Ihrer Regel können Sie diese Antworttabellen mithilfe der systemgenerierten Felder id und parent_id verknüpfen.

• Verarbeitung: Verwenden Sie die XP CRUD-Funktionalität, um Felder aus diesen Antworttabellen direkt Spalten in Ihrer lokalen Datenbank zum Einfügen oder Aktualisieren zuzuordnen.

Einen Success-Handler verwenden

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

• Implementierung:

  • Fügen Sie einen Success-Handler an die Aktion an, die den POST-Aufruf initiiert.

  • Rufen Sie die API-Antwortdaten im Success-Handler mithilfe der caller()-Funktion ab.

• Verarbeitung: Implementieren Sie benutzerdefinierte Logik im Success-Handler, 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 Content-Type ist JSON (application/json).

• Die einzige unterstützte Textkodierung ist UTF-8.

• Sammlungen sind auf die Rückgabe von 100 Elementen gleichzeitig begrenzt.

• Zusammengesetzte Primärschlüssel dürfen keine Kommas enthalten.

• Es wird nur Filterung über einfache Gleichheitsvergleiche unterstützt.