REST-API-Empfehlungen im Jitterbit App Builder

Übersicht

Dieses Dokument bietet Entwicklern, die eine mit dem App Builder kompatible REST-API implementieren möchten, Orientierung.

Für die Zwecke dieses Dokuments gehen wir davon aus, dass der Entwickler sich auf die Erstellung eines CRUD-REST-Dienstes konzentriert. 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.).

RESTful Designprinzipien

Soweit möglich, folgt die REST-API des App Builders diesen RESTful-Prinzipien:

• Dienste sind zustandslos.
• Endpunkte werden als Ressourcen modelliert.
• GET-Operationen sind sicher. Eine "sichere" Operation ist eine, die keine Nebenwirkungen hat. Zum Beispiel ändert das Abrufen einer Liste von Kunden nicht die Liste der Kunden.
• DELETE-Operationen sind unsicher, aber idempotent. Während die erste (erfolgreiche) Anfrage zum Löschen eines Elements einen 200-Statuscode zurückgibt, wird die zweite Anfrage einen 404-Statuscode zurückgeben.
• POST-Operationen sind weder sicher noch idempotent. Aus diesem Grund können POST-Operationen teilweise Daten enthalten.
• HTTP-Statuscodes zeigen an, ob ein Fehler aufgetreten ist.
• Medientypen werden verwendet, um eine Inhaltsverhandlung durchzuführen. Momentan unterstützt der App Builder jedoch nur JSON (application/json) und UTF-8.

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

• Ressourcenanforderungs- und -antwortkörper sind in einem Umschlag verpackt. Dies ermöglicht es dem App Builder, zusätzliche Informationen wie Ereignisnachrichten und Validierungsergebnisse einzuschließen.
• Ressourcenantworten sind keine Hypermedia: Sie enthalten keine Links zu anderen Ressourcen.

Umschlag

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

Anforderungs-Körperumschlag

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

Beispiel-JSON

{
  "item": {}
}

Antwortkörper-Hülle

Der Antwortkörper der App Builder REST API enthält diese Hüllen-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 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"
  }
}

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 durchblättern zu können.

Wenn möglich, sollte eine Anzahl der Datensätze in der Sammlung zurückgegeben werden. Dies ermöglicht es 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 Erstellen-Operation wird einen neuen Datensatz anlegen. Der Identifikator 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 (wie 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 Aktualisieren-Operation wird einen bestehenden Datensatz aktualisieren. Der Identifikator 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 (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-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
}

Löschen

Die Löschen-Operation wird einen Datensatz löschen. Der Identifikator für den Datensatz wird in der URL angegeben. Es muss kein Anforderungs-Body für ein DELETE gesendet werden.

HTTP-Methode

DELETE

Beispiel-URL

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

Beispiel-Antwort-Body 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

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

Filterung

Der App Builder bietet Unterstützung für eine Abfragefilterzeichenfolge. Die Abfragefilterzeichenfolge unterstützt eine Teilmenge der OData 4.0 Abfragezeichenfolgenspezifikation. Für Stringvergleiche 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

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

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

Typkonventionen

JSON-Typen

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

Daten

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 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-Antwortkörper JSON

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

JSON - Umwandlung von relationalen 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 Verwendung 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.