REST-API-Empfehlungen in Jitterbit App Builder

Einführung

Diese Seite bietet Orientierung für Entwickler, die eine mit App Builder kompatible REST-API implementieren möchten. Es wird davon ausgegangen, dass sich der Entwickler auf die Erstellung eines CRUD-REST-Service konzentriert. Viele der in einer CRUD-API verwendeten Prinzipien sind auf andere APIs anwendbar. Eine CRUD-API wird jedoch wahrscheinlich die umfassendsten Anforderungen haben, die mit App Builder interagieren (Paginierung, Suche, Filterung usw.).

Envelope

Die Request- und Response-Bodies der App Builder REST API werden in einem Envelope verpackt. Envelopes ermöglichen es, Daten außerhalb der Endpoint-Payload zu und von einem API-Endpoint zu senden.

Request-Body-Envelope

Der Request-Body der App Builder REST API enthält diese Envelope-Eigenschaften:

Beispiel-JSON

{
  "item": {}
}

Response-Body-Envelope

Der Response-Body der App Builder REST API enthält diese Envelope-Eigenschaften:

Beispiel-JSON

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

Validierungen

Wenn Fehler auftreten, wird ein Validierungsobjekt zum Validierungsarray im Response-Envelope 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 dein REST-Service unterstützen sollte. Einige Services werden natürlich bestimmte Methoden nicht implementieren (z. B. würde ein schreibgeschützter Service nur Get Single/Get Many-Methoden implementieren).

Einzelnen Datensatz abrufen

Die Operation „Get Single" gibt einen einzelnen Datensatz zurück. Die Kennung für den Datensatz wird 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"
  }
}

Mehrere Datensätze abrufen

Die Operation „Get Many" gibt mehrere Datensätze für eine Sammlung zurück. Diese Operation wird häufig zusammen mit 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 App Builder, die Datensatzanzahl in der Benutzeroberfläche anzuzeigen und die Benutzeroberfläche darüber zu informieren, wenn das Ende der Sammlung erreicht wurde.

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

Der Vorgang „Erstellen" erstellt einen neuen Datensatz. Die Kennung für den Datensatz befindet sich im JSON-Text.

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 Datensatz-Erstellungszeitstempel).

HTTP-Methode

POST

Beispiel-URL

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

Beispiel-Anforderungstext JSON

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

Beispiel-Antworttexttext JSON

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

Aktualisieren

Der Vorgang „Aktualisieren" aktualisiert einen vorhandenen Datensatz. Die Kennung für den Datensatz wird 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 (z. B. ein Datensatz-Aktualisierungszeitstempel).

HTTP-Methode

• PUT: Wird für eine vollständige Aktualisierung verwendet. Alle Parameter des Datensatzes müssen angegeben werden.

• POST: Wird für eine teilweise Aktualisierung verwendet. Nur erforderliche Parameter des Datensatzes müssen angegeben werden.

Beispiel-URL

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

Beispiel-Anforderungstext JSON

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

Beispiel-Antworttextkörper JSON

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

Löschen

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

HTTP-Methode

DELETE

Beispiel-URL

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

Beispiel-Antworttextkörper JSON

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

Abfrageparameter

Mehrere abrufen

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

Paginierung

Bei Sammlungen mit vielen Datensätzen ist es oft erforderlich, Paginierung zu unterstützen. Um Paginierung zu unterstützen, definiert App Builder die folgenden Parameter:

Sortierung

App Builder kann einfaches Sortieren von Feldern unterstützen.

Filterung

App Builder unterstützt Abfragefilterstränge. Der Abfragefilterstrang unterstützt eine Teilmenge der OData 4.0-Abfragestrang-Filterspezifikation. Bei Stringvergleichen können Platzhalter mit dem Zeichen % angegeben werden.

Operatoren

Vergleich

Logisch

Einschränkungen

• Keine arithmetischen Operatoren.

• Keine logischen Operatoren „or" oder „not".

• Keine Gruppierungsoperatoren.

• Keine Abfragefunktionen.

• Keine Parameteraliasnamen.

Suche

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

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

Typkonventionen

JSON-Typen

Grundsätzlich sollten Entwickler die nativen integrierten JSON-Typen bevorzugen. App Builder ordnet native JSON-Typen automatisch zu, daher wird die direkte Verwendung von Zahlen, booleschen Werten, Strings und Nullwerten empfohlen.

Daten

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

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

Versionierung

Um zukünftige Inkompatibilitäten zwischen REST-API-Versionen zu handhaben, enthält 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 Datensatzvorgaben zurückzugeben. Dies wird vor dem Erstellen eines Datensatzes für Fälle verwendet, in denen einige Daten vom REST-Server vorausgefüllt werden können.

HTTP-Methode

• GET

• POST

Beispiel-URL

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

Beispiel-Antworttextkörper JSON

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

JSON – Konvertierung relationaler Tabellen

App Builder bietet einen Mechanismus zur Konvertierung zwischen der internen relationalen Tabellenrepräsentation von Daten und dem JSON, das von REST-Endpunkten erwartet wird.

Arrays in Tabellen

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

Daher würde die folgende Konvertierung auf einen Endpoint namens "customers(get)" angewendet:

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
}

Resultierende Tabellenstruktur

customers(get)

customers(get)/items

Daten schreiben

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

Daher sollte man die Verwendung von JSON-Arrays wo möglich minimieren oder das Schreiben der Arrays in einem Objekt in einem separaten REST-API-Endpoint unterstützen.

Ein "customer"-Objekt kann beispielsweise mehrere Adressen enthalten. Ein Endpoint zum Schreiben des customer-Objekts und ein weiterer Endpoint zum Schreiben der Adressen ermöglichen es App Builder, sich leichter in die REST-API zu integrieren.