REST API im Jitterbit App Builder

Übersicht

REST ist ein architektonischer Stil für Webdienste. REST definiert eine Reihe von zustandslosen Operationen, die an Ressourcen durchgeführt werden können. Der App Builder ermöglicht es Entwicklern, Datenobjekte als REST-Ressourcen zu veröffentlichen. Verbraucher können Operationen an 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 so 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 dargestellt werden.

Wie der Dienst selbst bestimmt der Entwickler den Datenobjekt-Endpunkt. Zum Beispiel könnte das Datenobjekt "Kunden" 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 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 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, muss es alle Felder enthalten. Dies schränkt seine 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 Pseudo-Ereignis 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 200-Statuscode 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 enthalten, der den $q-Parameter als Teilstring 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 $count-Parameter. Standardmäßig gibt 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, sind nicht präfixiert.
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 Header-Informationen enthalten:

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

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.