REST- API im Jitterbit App Builder

Übersicht

REST ist ein Webservice-Architekturstil. REST definiert eine Reihe zustandsloser Operationen, die auf Ressourcen ausgeführt werden können. Mit App Builder können Entwickler Datenobjekte als REST-Ressourcen veröffentlichen. Nutzer können Operationen auf diesen Ressourcen ausführen, die in Ereignisaufrufe von Datenobjekten übersetzt werden.

Anwendungen als Webdienste

Die Umfeld von App Builder ist auf das Konzept einer Anwendung ausgerichtet. Obwohl Anwendungen typischerweise eine Benutzeroberfläche beschreiben, verfügen Anwendungen über mehrere Eigenschaften, die auch für Webdienste gelten:

Anwendungen bieten Zugriff auf mehrere Datenquellen.
Gruppen werden Berechtigungen für eine Anwendung erteilt.

App Builder erweitert das Anwendungskonzept um Webdienste. Entwickler können insbesondere einen Endpoint für eine Anwendung definieren. Beispielsweise könnte der Endpoint für die Anwendung „Sales“ „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. Im App Builder wird ein Datenobjekt als Sammlung dargestellt, wobei einzelne Zeilen als Elemente dieser Sammlung dargestellt werden.

Wie beim Dienst selbst bestimmt der Entwickler den Endpoint des Datenobjekts. Beispielsweise könnte das Datenobjekt „Kunden“ den Endpoint „Kunden“ haben. In diesem Fall könnte die entsprechende URI wie folgt aussehen:

https://example.com/App Builder/rest/v1/sales/customersDie URI für ein bestimmtes Element (eine Zeile) könnte folgendermaßen aussehen:
https://example.com/App Builder/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1Der Primärschlüssel erscheint im URI-Pfad.

Zusammengesetzte Primärschlüssel können durch Kommatrennung angegeben 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. Die REST- API von App Builder unterstützt die folgenden HTTP-Methoden:

GET /collection - Ruft die Elemente einer Sammlung ab. Dies entspricht dem Filterereignis.
POST /collection - Fügt der Sammlung ein Element hinzu. Dies entspricht dem Insert-Ereignis.
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 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 die folgenden HTTP-Methoden nicht:

HEAD - Mit der HEAD-Methode können Verbraucher die HTTP-Antwortheader abrufen. App Builder unterstützt diesen Operation derzeit 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 Benutzern, ein Element zu erstellen (beim Ansprechen der Sammlung) oder zu aktualisieren (beim Ansprechen 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 Benutzer Teile eines Elements aktualisieren. Dies wird derzeit über einen POST unterstützt. Normalerweise verwendet PATCH ein patch-spezifisches Format, was die Implementierung erschwert.

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

Neu - Das Ereignis „Neu“ des App Builders erstellt eine nicht persistente Zeile und wendet alle Standardwerte an. Verbraucher können das Ereignis „Neu“ nicht aufrufen.
Ändern - Interaktionen mit der Benutzeroberfläche lösen ein Pseudoereignis aus, 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 eigene Ereignisse definieren. Diese können derzeit nicht auf Ressourcenmethoden abgebildet werden.

RESTful-Designprinzipien

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

Dienste sind zustandslos.
Endpoints werden als Ressourcen modelliert. GET-Operationen sind sicher. Eine sichere Operation hat keine Nebenwirkungen. Beispielsweise ändert das Abrufen einer Kundenliste diese nicht. DELETE-Operationen sind unsicher, aber idempotent. Während die erste (erfolgreiche) Anfrage zum Löschen eines Elements den Statuscode 200 zurückgibt, gibt die zweite Anfrage einen Statuscode 404 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. Derzeit unterstützt App Builder jedoch nur JSON (application/json) und UTF-8.

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

Ressourcenantworten werden in einen Umschlag verpackt. Dadurch kann App Builder zusätzliche Informationen wie Ereignismeldungen und Validierungsergebnisse einbinden.
Ressourcenantworten sind keine Hypermedien: Sie enthalten keine Links zu anderen Ressourcen.

REST-URI-Konventionen

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

Paging über $offset und $limit Parameter. Die Standardgrenze liegt bei 10; die Höchstgrenze bei 100.
Sortierung über $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 absteigend zu sortieren. Beispielsweise lautet die Sortierspezifikation $sort=-country,companyName Die Sammlung wird absteigend nach Land und aufsteigend nach Firmenname sortiert.

Auswahl über eine $fields Parameter. Der $fields Der Parameter kann eine durch Kommas getrennte Liste von Feldnamen enthalten (z. B. $fields=customerId,country). Spezifisch ist das Sternchen (*), um alle Ressourcenfelder abzurufen (z. B. $fields=*). - Suche nach Stichworten über $q Parameter. Der $q Der Parameter nimmt eine Zeichenfolge auf und versucht, sie mit 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ß- und Kleinschreibung nicht berücksichtigt wird. - Filterung über einfache Gleichheitsvergleiche. Um die Ergebnisse einzugrenzen, geben Sie den Feldnamen und den Wert an (z. B. countryId=USA). - Zählen Sie über die $count Parameter. Standardmäßig gibt App Builder keine Gesamtzahl der Elemente in der Sammlung zurück. Um die Anzahl einzuschließen, fügen Sie den Parameter count hinzu (z. B. $count=true).

Konventionen für Parameter:

Parameter, die sich auf Ressourcenfelder beziehen, werden nicht vorangestellt.
Parameter, die auf die Sammlung selbst wirken, werden mit einem Dollarzeichen vorangestellt ($).

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 ValidationIds als Wert eines X- App Builder-Ignore-Warnings- Header in eine neue Anfrage an den Endpoint ein.

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 können maximal 100 Elemente gleichzeitig zurückgeben.

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

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