REST-API-Empfehlungen im Jitterbit App Builder

Einführung

Diese Seite bietet Entwicklern, die eine mit dem App Builder kompatible REST-API implementieren möchten, Orientierung. Es wird davon ausgegangen, dass der Entwickler darauf fokussiert ist, einen CRUD-REST-Dienst zu erstellen. Viele der Prinzipien, die in einer CRUD-API verwendet werden, sind auch auf andere APIs anwendbar. Eine CRUD-API wird jedoch wahrscheinlich die umfassendsten Anforderungen haben, die mit dem App Builder interagieren (Seiten, Suchen, Filtern usw.).

Umschlag

Die Anforderungs- und Antwortkörper der App Builder REST-API sind in einem Umschlag eingewickelt. Umschläge ermöglichen es, Daten zu einem API-Endpunkt und von diesem außerhalb der Nutzlast des Endpunkts zu senden.

Anforderungs-Körperumschlag

Der Anforderungs-Körper der App Builder REST-API enthält diese Umschlag-Eigenschaften:

Beispiel-JSON

{
  "item": {}
}

Antwort-Körperumschlag

Der Antwort-Körper der App Builder REST-API enthält diese Umschlag-Eigenschaften:

Beispiel-JSON

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

Validierungen

Wenn Fehler auftreten, wird ein Validierungsobjekt zum Validierungsarray im Antwortumschlag hinzugefügt. Das Validierungsobjekt hat die folgenden Eigenschaften:

Beispiel-JSON

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

Kernoperationen

Dies sind die grundlegenden Operationen, die Ihr REST-Dienst unterstützen sollte. Einige Dienste entscheiden sich natürlich dafür, bestimmte Methoden nicht zu implementieren (z. B. würde ein schreibgeschützter Dienst nur die Methoden "Get Single"/"Get Many" implementieren).

Einzelnes Element abrufen

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

HTTP-Methode

GET

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

Viele Elemente abrufen

Die Get Many-Operation gibt viele Datensätze für eine Sammlung zurück. Oft wird diese Operation zusammen mit der Paginierung verwendet, um eine Sammlung von Datensätzen zu durchsuchen.

Wenn möglich, sollte eine Anzahl der Datensätze in der Sammlung zurückgegeben werden. Dies ermöglicht es dem App Builder, die Anzahl der Datensätze in der Benutzeroberfläche anzuzeigen und die Benutzeroberfläche darüber zu informieren, wann das Ende der Sammlung erreicht ist.

HTTP-Methode

GET

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

Die Create-Operation erstellt einen neuen Datensatz. Der Bezeichner für den Datensatz befindet sich im JSON-Body.

Beachten Sie, dass der gesamte Datensatz in der Antwort zurückgegeben wird. Dies ist nützlich in Fällen, in denen einige Felder vom Server erstellt oder aktualisiert werden (z. B. ein Zeitstempel für die Erstellung des Datensatzes).

HTTP-Methode

POST

Beispiel-URL

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

Beispiel-Anforderungs-Body JSON

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

Beispiel-Antwort-Body JSON

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

Aktualisieren

Die Update-Operation aktualisiert einen vorhandenen Datensatz. Der Bezeichner für den Datensatz ist in der URL angegeben.

Beachten Sie, dass der gesamte Datensatz in der Antwort zurückgegeben wird. Dies ist nützlich in Fällen, in denen einige Felder vom Server erstellt oder aktualisiert werden (wie z. B. ein Zeitstempel für die Aktualisierung des Datensatzes).

HTTP-Methode

• PUT: Wird für ein vollständiges Update verwendet. Alle Parameter des Datensatzes müssen angegeben werden.

• POST: Wird für ein partielles Update verwendet. Nur die erforderlichen Parameter des Datensatzes müssen angegeben werden.

Beispiel-URL

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

Beispiel-Anforderungsinhalt JSON

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

Beispiel-Antwortinhalt JSON

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

Löschen

Die Löschoperation entfernt einen Datensatz. Der Bezeichner für den Datensatz wird in der URL angegeben. Es muss kein Anforderungsinhalt für ein DELETE gesendet werden.

HTTP-Methode

DELETE

Beispiel-URL

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

Beispiel-Antwortinhalt JSON

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

Abfrageparameter

Viele abrufen

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

Paging

Für Sammlungen, die viele Datensätze enthalten, ist es oft notwendig, Paging zu unterstützen. Um Paging zu unterstützen, definiert der App Builder die folgenden Parameter:

Sortierung

App Builder unterstützt die einfache Sortierung von Feldern.

Filterung

App Builder bietet Unterstützung für eine Abfragefilterzeichenfolge. Die Abfragefilterzeichenfolge unterstützt eine Teilmenge der OData 4.0 Abfragezeichenfolgenspezifikation. Für String-Vergleiche können Platzhalter mit dem Zeichen % angegeben werden.

Operatoren

Vergleich

Logisch

Einschränkungen

• Keine arithmetischen Operatoren.

• Keine oder/nicht logischen Operatoren.

• Keine Gruppierungsoperatoren.

• Keine Abfragefunktionen.

• Keine Parameter-Aliasnamen.

Suche

Der App Builder bietet einen Mechanismus, um nach Datensätzen in einer Sammlung zu suchen. Diese Suche erfolgt über alle durchsuchbaren Felder des Datensatzes.

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

Typkonventionen

JSON-Typen

Als allgemeine Regel sollten Entwickler die nativen integrierten JSON-Typen bevorzugen. Der App Builder mappt automatisch native JSON-Typen, sodass die direkte Verwendung von Zahlen, Booleans, Strings und Nullwerten empfohlen wird.

Daten

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

• https://de.wikipedia.org/wiki/ISO_8601

Versionierung

Um zukünftige Inkompatibilitäten zwischen REST-API-Versionen zu behandeln, enthält der App Builder eine Versionsnummer direkt in der REST-URL.

Beispiel-URL

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

Optionale Operationen

Weitere Operationen, die für eine CRUD-REST-API nützlich sein können.

Neu

Die neue Operation wird verwendet, um die Standardwerte eines Datensatzes zurückzugeben. Dies wird im Voraus verwendet, um einen Datensatz zu erstellen, wenn einige Daten möglicherweise vom REST-Server vorausgefüllt werden.

HTTP-Methode

• GET

• POST

Beispiel-URL

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

Beispiel-Antwort-Body JSON

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

JSON - Umwandlung relationaler Tabellen

App Builder bietet einen Mechanismus zur Umwandlung zwischen der internen relationalen Tabellenrepräsentation von Daten und dem von REST-Endpunkten erwarteten JSON.

Arrays in Tabellen

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

Daher würde die folgende Umwandlung für einen Endpunkt namens "customers(get)" gelten:

customers(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
}

Ergebnisstruktur der Tabelle

customers(get)

customers(get)/items

Daten schreiben

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, ist das Schreiben eines gesamten Objekts, das mehrere Arrays in einem einzigen App Builder-Ereignis umfasst, möglicherweise nicht unterstützt.

Daher sollte die Nutzung von JSON-Arrays, wo immer möglich, minimiert oder das Schreiben der Arrays in einem Objekt in einem separaten REST-API-Endpunkt unterstützt werden.

Ein "Kunden"-Objekt kann beispielsweise mehrere Adressen enthalten. Ein Endpunkt zum Schreiben des Kundenobjekts und ein weiterer Endpunkt zum Schreiben der Adressen ermöglichen es App Builder, einfacher mit Ihrer REST-API zu integrieren.