REST- API im Jitterbit App Builder

Übersicht

REST ist ein Webservice-Architekturstil. REST definiert eine Reihe zustandsloser Operationen, die an Ressourcen ausgeführt werden können. App Builder ermöglicht Entwicklern, Datenobjekte als REST-Ressourcen zu veröffentlichen. Verbraucher können an diesen Ressourcen Vorgänge ausführen, die in Ereignisaufrufe von Datenobjekten übersetzt werden.

Anwendungen als Webservices

Der App Builder Die Umfeld ist um das Konzept einer Anwendung herum organisiert. Obwohl Anwendungen normalerweise eine Benutzeroberfläche beschreiben, verfügen Anwendungen über mehrere Eigenschaften, die auch auf Webdienste zutreffen:

Anwendungen bieten Zugriff auf mehrere Datenquellen.
Gruppen werden Berechtigungen für eine Anwendung gewährt.

App Builder erweitert das Konzept einer Anwendung um Webdienste. Insbesondere haben Entwickler die Möglichkeit, einen Endpoint für eine Anwendung zu definieren. Der Endpoint für die Anwendung „Sales“ könnte beispielsweise „sales“ sein. Die entsprechende URI könnte folgendermaßen aussehen:

https://example.com/App Builder/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 In einfacheren Begriffen wird ein Datenobjekt als eine Sammlung dargestellt, wobei die einzelnen Zeilen als Elemente in dieser Sammlung repräsentiert werden.

Wie beim Dienst selbst bestimmt der Entwickler den Endpoint des Datenobjekts. Das Datenobjekt „Customers“ könnte beispielsweise den Endpoint „customers“ haben. In diesem Fall könnte die entsprechende URI folgendermaßen aussehen:

https://example.com/App Builder/rest/v1/sales/customers

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

https://example.com/App Builder/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/App Builder/rest/v1/sales/customers/abc,def

Ereignisse als HTTP-Methoden

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

GET /collection - Ruft die Elemente innerhalb einer Sammlung ab. Dies wird dem Filterereignis zugeordnet.
POST /collection - Fügt der Sammlung ein Element hinzu. Dies wird dem Insert-Ereignis zugeordnet.
GET /collection/item - Ruft ein einzelnes Element aus der Sammlung ab. Dies wird dem Filterereignis zugeordnet.
POST /collection/item - Aktualisiert ein Element in der Sammlung. Dies wird dem Update-Ereignis zugeordnet.
DELETE /collection/item - Löscht ein Element aus der Sammlung. Dies entspricht dem DELETE-Ereignis.

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

HEAD - Die HEAD-Methode ermöglicht es Verbrauchern, die HTTP-Antwortheader abzurufen. Im Moment App Builder unterstützt diesen Operation nicht.
OPTIONEN - Mit der OPTIONS-Methode können Verbraucher bestimmen, welche Methoden unterstützt werden.
PUT (Sammlung oder Element) - Die PUT-Methode ermöglicht es Verbrauchern, ein Element zu erstellen (beim Adressieren der Sammlung) oder ein Element zu aktualisieren (beim Adressieren des Elements). Da PUT jedoch idempotent ist, muss es alle Felder einschließen. Dies schränkt seine Nützlichkeit in vielen Szenarien ein.
PATCH - Mit der PATCH-Methode können Verbraucher Teile eines Elements aktualisieren. Dies wird derzeit über einen POST unterstützt. Normalerweise verwendet PATCH ein patch-spezifisches Format, was die Implementierung komplizierter macht.

Nicht alle App Builder Veranstaltungen können veröffentlicht werden:

Neu - App Builder Das neue Ereignis von erstellt eine nicht persistente Zeile und wendet alle Standardwerte an. Verbraucher können das neue Ereignis nicht aufrufen.
Ändern - Interaktionen mit der Benutzeroberfläche rufen ein Pseudoereignis auf, das Standardwerte und Validierungen ausführt, ohne Änderungen dauerhaft zu speichern. Verbraucher können das Änderungsereignis nicht simulieren.
Benutzerdefinierte Ereignisse - Zusätzlich zu den intrinsischen Ereignissen können Entwickler ihre eigenen Ereignisse definieren. Derzeit können diese nicht Ressourcenmethoden zugeordnet werden.

RESTful-Designprinzipien

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

Dienste sind zustandslos.
Endpoints werden als Ressourcen modelliert.
GET-Operationen sind sicher. Eine „sichere“ Operation ist eine, die keine Nebenwirkungen hat. Beispielsweise ändert das Abrufen einer Kundenliste die Kundenliste nicht.
DELETE-Operationen sind unsicher, aber idempotent. Während jedoch die erste (erfolgreiche) Anfrage zum Löschen eines Elements den Statuscode 200 zurückgibt, gibt die zweite Anfrage einen 404-Statuscode zurück.
POST-Operationen sind weder sicher noch idempotent. Aus diesem Grund können POST-Operationen Teildaten enthalten.
HTTP-Statuscodes zeigen an, ob ein Fehler aufgetreten ist.
Medientypen werden zur Inhaltsverhandlung verwendet. Im Moment jedoch App Builder unterstützt nur JSON (application/json) und UTF-8.

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

Ressourcenantworten werden in einen Umschlag verpackt. Dies ermöglicht App Builder um zusätzliche Informationen wie Ereignismeldungen und Validierungsergebnisse einzuschließen.
Ressourcenantworten sind keine Hypermedien: Sie enthalten keine Links zu anderen Ressourcen.

REST-URI-Konventionen

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

Paging über $offset und $limit Parameter. Die Standardgrenze liegt bei 10, die Höchstgrenze bei 100.
Sortierung über eine $sort Parameter. Der $sort Der Parameter kann eine durch Kommas getrennte Liste von Feldnamen enthalten. Stellen Sie dem Feldnamen einen Bindestrich (-) voran, um das Feld in absteigender Reihenfolge zu sortieren. Beispielsweise lautet die Sortierspezifikation $sort=-country,companyName würde die Sammlung nach Land (absteigend) und Firmenname (aufsteigend) sortieren.
Auswahl über eine $fields Parameter. Der $fields Der Parameter kann eine durch Kommas getrennte Liste von Feldnamen enthalten (z. B. $fields=customerId,country). Konkret bedeutet das Asterisk (*), um alle Ressourcenfelder abzurufen (z. B. $fields=*).
Suche nach Stichworten über eine $q Parameter. Der $q Der Parameter nimmt eine Zeichenfolge auf und versucht, sie mit den Spaltenwerten abzugleichen. Alle Tabellenzeilen, die mindestens einen Spaltenwert haben, der den Parameter $q als Teilzeichenfolge enthält, werden zurückgegeben (z. B. $q=miami). Beachten Sie, dass bei der Übereinstimmung die Groß-/Kleinschreibung nicht beachtet wird.
Filterung über einfache Gleichheitsvergleiche. Um die Ergebnisse einzuschränken, geben Sie den Feldnamen und den Wert an (z. B. countryId=USA).
Zählen Sie über die $count Parameter. Standardmäßig App Builder gibt keine Gesamtzahl der Elemente in der Sammlung zurück. Um die Anzahl einzuschließen, hängen Sie den Parameter count an (z. B. $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 ($).

Validierung

Ein Ereignis kann als Teil der Antwort einen oder mehrere Fehler, Warnungen oder informative Validierungsergebnisse zurückgeben. Jede Validierung enthält eine Validierungs-ID, eine Nachricht (definiert in der IDE) und den Schweregrad der Validierung („Fehler“, „Warnung“, „Information“).

Wenn Sie eine Warnung umgehen möchten, fügen Sie die bereitgestellten Validierungs-IDs als Wert eines X- ein App Builder-Ignore-Warnings Header in einer neuen Anfrage an den Endpoint.

Beispielsweise 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
}

Eine neue Anfrage (an denselben Endpoint und dieselben Daten) müsste die folgenden Header Informationen enthalten:

X-App Builder-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 gleichzeitige Rückgabe von 100 Elementen beschränkt.
Zusammengesetzte Primärschlüssel dürfen keine Kommas enthalten.
Es wird nur das Filtern über einfache Gleichheitsvergleiche unterstützt.