REST-APIs im Jitterbit App Builder

Einführung

Der App Builder bietet zwei Hauptmöglichkeiten zur Integration mit REST-APIs:

• Verbrauchen (durch manuelle Konfiguration oder durch Importieren eines OpenAPI-Dokuments) externer REST-APIs, um Daten in Ihre Anwendungen zu bringen, oder
• Veröffentlichen der Daten Ihrer App Builder-Anwendung als REST-API, die von anderen Systemen konsumiert werden kann.

Konzepte und Prinzipien

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 auf Webdienste zutreffen:

• 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 eine Sales-Anwendung sales sein. Die entsprechende URI könnte folgendermaßen aussehen:

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

Datenobjekte als Ressourcen

Das organisatorische 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 Customers-Datenobjekt 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 einen bestimmten Artikel (Zeile) könnte so 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 Filter-Ereignis.

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

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

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

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

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. Im Moment 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 Neu-Ereignis von App Builder erstellt eine nicht-persistente Zeile und wendet alle Standardwerte an. Verbraucher können das Neu-Ereignis nicht aufrufen.

• Änderung: Interaktionen mit der Benutzeroberfläche lösen ein Pseudo-Ereignis aus, das Standardwerte und Validierungen ausführt, ohne Änderungen zu speichern. Verbraucher können das Änderung-Ereignis 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 200-Statuscode zurückgibt, wird die zweite Anfrage einen 404-Statuscode 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. Momentan 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 keine 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 country in absteigender und nach companyName in aufsteigender Reihenfolge sortieren.

• Auswahl über einen $fields-Parameter. Der $fields-Parameter kann eine durch Kommas getrennte Liste von Feldnamen annehmen (zum Beispiel, $fields=customerId,country). Verwenden Sie ein Sternchen (*), um alle Ressourcenfelder abzurufen (zum Beispiel, $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 enthalten, der den $q-Parameter als Teilstring enthält, werden zurückgegeben (zum Beispiel, $q=miami). Die Übereinstimmung ist nicht case-sensitiv.

• Filtern über einfache Gleichheitsvergleiche. Um die Ergebnisse einzuschränken, geben Sie den Feldnamen und den Wert an (zum Beispiel, countryId=USA).

• Zählen über den $count-Parameter. 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 (zum Beispiel, $count=true).

Konventionen für Parameter:

• Parameter, die sich auf Ressourcenfelder beziehen, sind nicht mit einem Präfix versehen.

• Parameter, die auf die Sammlung selbst wirken, sind mit einem Dollarzeichen ($) präfixiert.

Validation

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

Um eine Warnung zu umgehen, fügen Sie die bereitgestellten validationIds als Wert eines X-Vinyl-Ignore-Warnings-Headers in einer neuen Anfrage an den Endpunkt hinzu. 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 zu umgehen, die diese Antwort enthält, 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"

Handle POST responses

Es gibt zwei Möglichkeiten, die von einem POST-Aufruf zurückgegebenen Daten zu erfassen und zu verarbeiten: Bindung 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 von 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 von App Builder.

  • Übergeben Sie die erforderlichen Parameter für den POST-Aufruf und ordnen Sie diese den entsprechenden Feldern in Ihrer externen API zu.

• Zugriff auf Antwortdaten:

  • Nach erfolgreicher Ausführung des POST wird die Antwortdaten der API in den automatisch generierten Antworttabellen in 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 den Spalten in Ihrer lokalen Datenbank für die Einfügung oder Aktualisierung zuzuordnen.

Verwenden Sie einen Erfolgs-Handler

Die Verwendung eines Erfolgs-Handlers 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 Erfolgs-Handler an die Aktion an, die den POST-Aufruf initiiert.

  • Rufen Sie die API-Antwortdaten innerhalb des Erfolgs-Handlers mit der caller()-Funktion ab.

• Verarbeitung: Implementieren Sie benutzerdefinierte Logik innerhalb des Erfolgs-Handlers, 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.

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

• Es wird nur das Filtern über einfache Gleichheitsvergleiche unterstützt.