REST API Empfehlungen im Jitterbit App Builder

Übersicht

Dieses Dokument bietet eine Anleitung für Entwickler, die eine App Builder-kompatible REST- API implementieren möchten.

Für dieses Dokument gehen wir davon aus, dass der Entwickler einen CRUD-REST-Dienst erstellen möchte. Viele der in einer CRUD- API verwendeten Prinzipien sind auch auf andere APIs anwendbar. Eine CRUD API stellt jedoch wahrscheinlich die umfassendsten Anforderungen im Zusammenspiel mit dem App Builder (Paginierung, Suche, Filterung usw.).

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:

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

Umschlag

Die Anforderungs- und Antworttexte der App Builder REST- API sind in einem Umschlag verpackt. Umschläge ermöglichen das Senden von Daten von und zu einem API Endpoint außerhalb der Endpoint.

Umschlag des Anforderungstexts

Der Anforderungstext der App Builder REST- API enthält die folgenden Umschlageigenschaften:

Immobilienname	Beschreibung
item	Die Endpoint.

Beispiel-JSON

{
  "item": {}
}

Antworttext-Umschlag

Der Antworttext der App Builder REST- API enthält die folgenden Umschlageigenschaften:

Immobilienname	Beschreibung
message	Die Erfolgs- oder Fehlermeldung für das Ereignis.
status	Dies ist der (duplizierte) HTTP-Statuscode.
Validierungen	Ein Array von Validierungsfehlern/Warnungen für den aufgerufenen Endpoint.
item oder items	Die Endpoint - entweder ein einzelnes Element oder eine Sammlung von Elementen.

Beispiel-JSON

{
  "message": "",
  "status": 200,
  "validations": [],
  "items": []
}

Validierungen

Bei Fehlern wird dem Validierungs-Array im Antwort-Envelope ein Validierungsobjekt hinzugefügt. Das Validierungsobjekt hat folgende Eigenschaften:

Eigenschaftsname	Beschreibung
message	Die Validierungsnachricht.
severity	Der Schweregrad der Validierung: error warning information
field	Das von der Validierung referenzierte Feld.

Beispiel-JSON

{
  "message": "",
  "status": 400,
  "validations": [
    {
      "message": "CustomerId is mandatory.",
      "severity": "error",
      "field": "customerId"
    },
    {
      "message": "CompanyName is mandatory.",
      "severity": "error",
      "field": "companyName"
    }
  ],
}

Kerngeschäfte

Dies sind die grundlegenden Operationen, die Ihr REST-Dienst unterstützen sollte. Manche Dienste implementieren bestimmte Methoden natürlich nicht (z. B. implementiert ein schreibgeschützter Dienst nur die Methoden „Get Single“ und „Get Many“).

Werde Single

Der Operation „Get Single“ gibt einen einzelnen Datensatz zurück. Die Kennung für den Datensatz ist in der URL angegeben.

HTTP-Methode

ERHALTEN

Beispiel URL

https://example.com/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1

Beispiel-JSON

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
}

Holen Sie sich viele

Die Operation „Viele abrufen“ gibt viele Datensätze für eine Sammlung zurück. Diese Operation wird häufig zusammen mit der Paginierung verwendet, um eine Datensatzsammlung durchzusehen.

Wenn möglich, sollte die Anzahl der Datensätze in der Sammlung zurückgegeben werden. Dadurch kann App Builder die Datensatzanzahl in der Benutzeroberfläche anzeigen und die Benutzeroberfläche informieren, wenn das Ende der Sammlung erreicht ist.

HTTP-Methode

ERHALTEN

Beispiel URL

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

Beispiel-JSON

{
  "count": 2,
  "items": [
    {
      "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
      "name": "John Henry",
      "address": "130 Plutonium Drive"
    },
    {
      "customerId": "9775de33-08fc-4cd2-98ef-d91f3d5355b1",
      "name": "Sally Keith",
      "address": "4500 Neutrino Road"
    }
  ],
  // envelope properties
}

Erstellen

Mit dem Operation „Erstellen“ wird ein neuer Datensatz erstellt. Die Kennung für den Datensatz ist im JSON-Textkörper enthalten.

Beachten Sie, dass der gesamte Datensatz in der Antwort wiedergegeben wird. Dies ist nützlich, wenn einige Felder vom Server erstellt oder aktualisiert werden (z. B. ein Zeitstempel für die Datensatzerstellung).

HTTP-Methode

POST

Beispiel URL

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

Beispiel für den Anforderungstext JSON

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
}

Beispiel für den Antworttext JSON

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
  // envelope properties
}

Aktualisieren

Mit dem Update Operation wird ein vorhandener Datensatz aktualisiert. Die Kennung für den Datensatz ist in der URL angegeben.

Beachten Sie, dass der gesamte Datensatz in der Antwort wiedergegeben wird. Dies ist nützlich, wenn einige Felder vom Server erstellt oder aktualisiert werden (z. B. ein Zeitstempel für die Datensatzaktualisierung).

HTTP-Methode

PUT - Für eine vollständige Aktualisierung. Alle Parameter des Datensatzes müssen angegeben werden.
POST - Für eine teilweise Aktualisierung. Nur die obligatorischen Parameter des Datensatzes müssen angegeben werden.

Beispiel URL

https://example.com/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1

Beispiel für den Anforderungstext JSON

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
}

Beispiel für den Antworttext JSON

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
  // envelope properties
}

Löschen

Der Operation löscht einen Datensatz. Die Kennung für den Datensatz ist in der URL angegeben. Für einen Löschvorgang muss kein Anforderungstext gesendet werden.

HTTP-Methode

LÖSCHEN

Beispiel URL

https://example.com/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1

Beispiel für den Antworttext JSON

{
  "item": {
    "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
    "name": "John Henry",
    "address": "130 Plutonium Drive"
  }
}

Abfrageparameter

Holen Sie sich viele

Auf Sammlungsebene sollte Ihr REST- Endpoint die folgenden Funktionen unterstützen.

Seitenaufruf

Bei Sammlungen mit vielen Datensätzen ist häufig die Unterstützung der Seitennummerierung erforderlich. Zur Unterstützung der Seitennummerierung definiert App Builder die folgenden Parameter:

Abfrageparameter	Beschreibung	Beispiel
$limit	Die maximale Anzahl der Datensätze, die in einer Anfrage abgerufen werden können.	`$limit=10`
$offset	Ab welchem Datensatz-Offset der Abruf beginnen soll. Offsets sind nullbasiert, daher wird bei Angabe von 0 der erste Datensatz der Sammlung abgerufen.	`$offset=10`
$count	Ein Boolescher Wert, der angibt, ob die Anzahl der Sammlungen zurückgegeben werden soll. Im App Builder wird dieser Parameter standardmäßig als „false“ betrachtet.	`$count=true`

Sortierung

App Builder kann eine einfache Sortierung von Feldern unterstützen.

Abfrageparameter	Beschreibung	Beispiel
$sort	Eine durch Kommas getrennte Liste von Feldnamen, nach denen sortiert werden soll. Stellen Sie dem Feldnamen einen Bindestrich (-) voran, um das Feld absteigend zu sortieren. Im angegebenen Beispiel sortieren Sie die Sammlung nach Land (absteigend) und Firmenname (aufsteigend).	`$sort=-country,companyName`

Filtern

App Builder bietet Unterstützung für eine Abfrage. Die Abfrage unterstützt eine Teilmenge der OData 4.0 Abfrage. Für Zeichenfolgenvergleiche können Platzhalter mit dem % Zeichen.

Abfrageparameter	Beschreibung	Beispiel
$filter	Eine Abfrage im OData 4.0-Stil, die Daten filtert	`$filter=country eq 'united%'`

Betreiber

Vergleich

Operator	Beschreibung	Beispiel
eq	Gleich dem Wert.	`categoryId eq 42`
neq	Ungleich dem Wert.	`categoryId neq 42`
gt	Größer als der Wert.	`price gt 100`
lt	Kleiner als der Wert.	`price lt 100`
ge	Größer oder gleich dem Wert.	`price ge 100`
le	Kleiner oder gleich dem Wert.	`price le 100`
in	Entspricht jedem Wert in der Liste.	`categoryId in (1, 2, 3)`

Logisch

Operator	Beschreibung	Beispiel
und	Logisches UND	`price gt 100 and categoryId in (1,2,3)`

Einschränkungen

Keine Rechenoperatoren
Keine logischen Oder/Nicht-Operatoren
Keine Gruppierungsoperatoren
Abfrage Abfragefunktionen
Keine Parameter-Aliase

Suchen

App Builder bietet einen Mechanismus zur Suche nach Datensätzen in einer Sammlung. Diese Suche erfolgt über alle durchsuchbaren Felder des Datensatzes.

App Builder fügt standardmäßig Platzhalter am Anfang und Ende der Suchzeichenfolge hinzu.

Abfrageparameter	Beschreibung	Beispiel
$q	Ein Suchstring, der auf alle durchsuchbaren Spalten eines Datensatzes angewendet wird.	`$q=hello`

Typkonventionen

JSON-Typen

Entwickler sollten grundsätzlich die integrierten nativen JSON-Typen verwenden. App Builder ordnet native JSON-Typen automatisch zu, daher wird die direkte Verwendung von Zahlen, Booleschen Werten, Zeichenfolgen und Nullen empfohlen.

Termine

App Builder kodiert Datumsangaben im ISO 8601-Format. Alle Datumsangaben werden in UTC serialisiert.

https://en.wikipedia.org/wiki/ISO_8601

Versionierung

Um zukünftige Inkompatibilitäten zwischen REST API Versionen zu bewältigen, fügt App Builder eine Versionsnummer direkt in die REST- URL ein.

Beispiel URL

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

Optionale Operationen

Andere Vorgänge, deren Einbindung in eine CRUD-REST- API sinnvoll sein kann.

Neu

Die neue Operation dient zur Rückgabe von Datensatzstandardwerten. Dies wird vor der Erstellung eines Datensatzes für Fälle verwendet, in denen einige Daten vom REST-Server vorab ausgefüllt werden können.

HTTP-Methode

GET
POST.

Beispiel URL

https://example.com/rest/v1/sales/customers(new)

Beispiel für den Antworttext JSON

{
  "item": {
    "customerId": null,
    "daysActive": 0
  }
  // envelope properties
}

JSON - Konvertierung relationaler Tabellen

App Builder bietet einen Mechanismus zur Konvertierung zwischen der internen relationalen Tabellendarstellung von Daten und dem von REST- Endpoints erwarteten JSON.

Arrays zu Tabellen

Jedes Array in einer JSON-Struktur wird im App Builder als separate relationale Tabelle betrachtet.

Daher würde die folgende Konvertierung auf einen Endpoint mit dem Namen „customers(get)“ zutreffen:

Kunden (get) JSON

{
  "count": 2,
  "message": "Sample message",
  "status": 200,
  "items": [
    {
      "customerId": "b603b276-a9bf-4328-88ff-8994176c38d1",
      "name": "John Henry",
      "address": "130 Plutonium Drive"
    },
    {
      "customerId": "9775de33-08fc-4cd2-98ef-d91f3d5355b1",
      "name": "Sally Keith",
      "address": "4500 Neutrino Road"
    }
  ],
  // envelope properties
}

Resultierende Tabellenstruktur

"Kunden (erhalten)"

Anzahl	Nachricht	Status
2	Beispielnachricht	200

"Kunden(abrufen)/Artikel"

Kunden-ID	Name	Adresse
9775de33-08fc-4cd2-98ef-d91f3d5355b1	Sally Keith	4500 Neutrino Road
b603b276-a9bf-4328-88ff-8994176c38d1	John Henry	130 Plutoniumantrieb

Schreiben von Daten

Derzeit unterstützt App Builder nur das Schreiben in eine einzelne Tabelle während eines Ereignisses. Da jedes JSON-Array als separate Tabelle betrachtet wird, wird das Schreiben eines gesamten Objekts, das mehrere Arrays umfasst, in einem einzelnen App Builder Ereignis möglicherweise nicht unterstützt.

Versuchen Sie daher, die Verwendung von JSON-Arrays nach Möglichkeit zu minimieren, oder unterstützen Sie das Schreiben der Arrays in einem Objekt in einem separaten REST- API Endpoint.

Beispielsweise kann ein „Kunden“-Objekt mehrere Adressen enthalten. Wenn Sie über einen Endpoint zum Schreiben des Kundenobjekts und einen anderen Endpoint zum Schreiben der Adressen verfügen, lässt sich App Builder einfacher in Ihre REST- API integrieren.