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 Ihre Anwendungen zu bringen, oder
• Die Daten Ihrer App Builder-Anwendung als REST-API veröffentlichen, damit andere Systeme diese nutzen können. Sie können auch ein OpenAPI-(Swagger)-Dokument veröffentlichen, das diese API beschreibt.

Konzepte und Prinzipien

Anwendungen als Webservices

Die App Builder-Designumgebung ist um das Konzept einer Anwendung organisiert. Obwohl Anwendungen typischerweise eine Benutzeroberfläche beschreiben, verfügen Anwendungen über 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. Der entsprechende URI könnte wie folgt 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 Endpunkt des Datenobjekts. Beispielsweise könnte das Datenobjekt Customers einen Endpunkt von customers haben. In diesem Fall könnte der entsprechende URI wie folgt aussehen:

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

Der URI für ein bestimmtes Element (Zeile) könnte wie folgt 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 einen Satz 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 diesen Vorgang 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 patchspezifisches Format, was die Implementierung erschwert.

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

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

• Change: Interaktionen mit der Benutzeroberfläche rufen ein Pseudo-Event auf, das Standardwerte und Validierungen ausführt, ohne Änderungen zu speichern. Consumer 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 auf die oben genannten Standard-Ressourcenmethoden abgebildet 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 für ein Geschäftsobjekt definiert ist. Dies führt das Ziel-Event und alle damit verbundenen Aktionen aus, wie z. B. CRUD-Operationen, Benachrichtigungen, gespeicherte Prozeduren sowie Geschäftsregeln oder Validierungen.

Seit App Builder 4.67 ist die Event-Bereitstellung über die REST-API optional: Für jede REST-Ressource müssen Entwickler explizit auswählen, welche Events verfügbar sind, und jedem einen URL-freundlichen Namen zuweisen, indem sie die Registerkarte Events in den Ressourceneigenschaften verwenden. Events, die vor App Builder 4.67 erstellt wurden, bleiben automatisch bereitgestellt und verwenden ihren ursprünglichen Namen für Rückwärtskompatibilität.

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 für einen 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:

• Ressourcenresponses werden in einer Hülle verpackt. Dies ermöglicht App Builder, zusätzliche Informationen wie Event-Meldungen und Validierungsergebnisse einzubeziehen.

• Ressourcenresponses 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 in absteigender Reihenfolge und companyName in aufsteigender Reihenfolge 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 akzeptiert eine Zeichenkette und versucht, diese mit Spaltenwerten abzugleichen. Alle Tabellenzeilen, bei denen mindestens ein Spaltenwert den $q-Parameter als Teilzeichenkette enthält, werden zurückgegeben (beispielsweise $q=miami). Der Abgleich unterscheidet nicht zwischen Groß- und Kleinschreibung.

• Filterung durch einfache Gleichheitsvergleiche. Um die Ergebnisse einzugrenzen, geben Sie den Feldnamen und den Wert an (beispielsweise countryId=USA).

• Zählung über den $count-Parameter. 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 (beispielsweise $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 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 verfügbar.

  • 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 zuzuordnen und einzufügen oder zu aktualisieren.

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 durch einfache Gleichheitsvergleiche unterstützt.