REST- API Empfehlungen im Jitterbit App Builder

Übersicht

Dieses Dokument bietet Anleitungen für Entwickler, die Folgendes implementieren möchten: an App Builder-kompatible REST- API.

Für die Zwecke dieses Dokuments gehen wir davon aus, dass der Entwickler sich auf die Erstellung eines CRUD-REST-Dienstes konzentriert. Viele der in einer CRUD API verwendeten Prinzipien sind auch auf andere APIs anwendbar. Eine CRUD API hat jedoch wahrscheinlich die umfassendsten Anforderungen, die mit App Builder(Seitenumbruch, Suche, Filterung usw.).

RESTful-Designprinzipien

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

• Dienste sind zustandslos.
• Endpoints werden als Ressourcen modelliert.
• GET-Operationen sind sicher. Eine „sichere“ Operation ist eine, die keine Nebenwirkungen hat. Beispielsweise ändert das Abrufen einer Kundenliste die Kundenliste nicht.
• DELETE-Operationen sind unsicher, aber idempotent. Während jedoch die erste (erfolgreiche) Anfrage zum Löschen eines Elements den Statuscode 200 zurückgibt, gibt die zweite Anfrage einen 404-Statuscode 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. Im Moment jedoch App Builder unterstützt 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. Dies ermöglicht App Builder um zusätzliche Informationen wie Ereignismeldungen und Validierungsergebnisse einzuschließen.
• Ressourcenantworten sind keine Hypermedien: Sie enthalten keine Links zu anderen Ressourcen.

Umschlag

App Builder REST- API Anforderungs- und-Antworttexte werden in einen Umschlag verpackt. Umschläge ermöglichen das Senden von Daten zu und von einem API Payload Endpoint der Endpoint.

Umschlag des Anforderungstexts

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

Beispiel-JSON

{
  "item": {}
}

Umschlag des Antworttexts

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

Beispiel-JSON

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

Validierungen

Wenn Fehler auftreten, wird dem Validierungsarray im Antwortumschlag ein Validierungsobjekt 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"
    }
  ],
}

Kerngeschäfte

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

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

Der Operation „Viele abrufen“ gibt viele Datensätze für eine Sammlung zurück. Dieser Operation wird häufig zusammen mit der Paginierung verwendet, um das Durchsehen einer Sammlung von Datensätzen zu ermöglichen.

Wenn möglich, sollte eine Anzahl der Datensätze in der Sammlung zurückgegeben werden. Dies ermöglicht App Builder um die Datensatzanzahl in der Benutzeroberfläche anzuzeigen und die Benutzeroberfläche zu informieren, wenn das Ende der Sammlung erreicht wurde.

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

Der Operation „Erstellen“ erstellt einen neuen Datensatz. Die Kennung für den Datensatz ist im JSON-Textkörper vorhanden.

Beachten Sie, dass der gesamte Datensatz in der Antwort wiedergegeben wird. Dies ist in Fällen nützlich, in denen 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

Beispielanforderungstext 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

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

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

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 obligatorische Parameter des Datensatzes müssen angegeben werden.

Beispiel URL

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

Beispielanforderungstext 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, die viele Datensätze enthalten, ist es oft notwendig, die Seitennummerierung zu unterstützen. Um die Seitennummerierung zu unterstützen, App Builder definiert die folgenden Parameter:

Sortierung

App Builder kann einfaches Sortieren von Feldern unterstützen.

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.

Betreiber

Vergleich

Logisch

Einschränkungen

• Keine Rechenoperatoren
• Keine logischen „oder/nicht“-Operatoren
• Keine Gruppierungsoperatoren
• Keine Abfrage
• Keine Parameter-Aliase

Suchen

App Builder bietet einen Mechanismus zum Suchen nach Datensätzen in einer Sammlung. Diese Suche funktioniert in allen durchsuchbaren Feldern des Datensatzes.

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

Typkonventionen

JSON-Typen

Als allgemeine Regel sollten Entwickler vorzugsweise die nativen integrierten 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 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 bewältigen, App Builder enthält eine Versionsnummer direkt in der REST- URL.

Beispiel URL

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

Optionale Operationen

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

Neu

Der neue Operation wird verwendet, um Datensatzstandardwerte zurückzugeben. Dies wird vor dem Erstellen eines Datensatzes für Fälle verwendet, in denen einige Daten möglicherweise vom REST-Server vorab ausgefüllt werden.

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 als separate relationale Tabelle innerhalb von App Builder.

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

Kunden (abrufen) 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) "

"Kunden(get)/Artikel"

Schreiben von Daten

Momentan, App Builder unterstützt 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 in einer einzigen Tabelle umfasst, App Builder Das Ereignis wird möglicherweise nicht unterstützt.

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

Beispielsweise kann ein Objekt „Kunde“ mehrere Adressen enthalten. Wenn ein Endpoint zum Schreiben des Kundenobjekts und ein anderer Endpoint zum Schreiben der Adressen vorhanden ist, App Builder um die Integration mit Ihrer REST- API zu vereinfachen.