Bei der Gestaltung und Entwicklung einer API-Integration fokussiert man sich schnell so sehr auf die Einzelheiten des Betriebs, der Attribute und Parameter, dass man Faktoren aus den Augen verliert, die die Leistung, Stabilität und Pflege der Integration erheblich verbessern würden.
Diesen Faktoren die verdiente Aufmerksamkeit zu widmen, macht möglicherweise den Unterschied zwischen einer unzuverlässigen und einer grundsoliden Integration. Um sicherzustellen, dass Ihre Integration das bestmögliche Niveau hat, empfehlen wir nachdrücklich, diese vier bewährten Vorgehensweisen für Smartsheet-APIs umzusetzen:
1. Seien Sie effizient: Verwenden Sie Massenvorgänge
Verwenden Sie wann immer möglich API-Massenvorgänge, um maximal effizient zu arbeiten. Ein API-Massenvorgang ermöglicht es Ihnen, mehrere Elemente mit einer einzigen API-Anforderung hinzuzufügen, zu aktualisieren oder zu löschen.
Wenn Sie beispielsweise 10 Zeilen in einem Sheet aktualisieren müssen, verwenden Sie dafür eine Anforderung Zeilen aktualisieren, anstatt 10 einzelne Anforderungen (eine pro Zeile) auszuführen.
Massenvorgänge verbessern die Effizienz erheblich, da die Anzahl der ausgehenden Aufrufe Ihrer Integration reduziert wird. Das minimiert das Risiko, die Ratenbegrenzung zu erreichen (da ein Massenvorgang nur als eine Anforderung auf die Begrenzung angerechnet wird).
Mithilfe der folgenden API-Vorgänge können Sie aktuell die folgenden Aufgaben für mehrere Elemente gleichzeitig ausführen:
Wir fügen in Zukunft noch weitere Massenvorgänge hinzu – halten Sie also Ausschau nach diesen zusätzlichen Möglichkeiten, die Effizienz zu verbessern. Denken Sie daran: Nach Möglichkeit Massenvorgänge zu nutzen, ist eine bewährte Vorgehensweise.
Tipp: Lassen Sie Teilerfolge zu
Standardmäßig schlägt der gesamte Vorgang fehl, wenn während eines Massenvorgangs ein Fehler ausgegeben wird. Wenn Sie beispielsweise eine Anforderung zum Aktualisieren von Zeilen senden und eines der Zeilenobjekte in der Anforderung ungültig ist, schlägt der gesamte Vorgang fehl und keine der Zeilen wird aktualisiert.
Sie haben jedoch die Option, bei Massenanforderungen einen Teilerfolg zuzulassen. Wenn Sie Teilerfolge zulassen, werden die erfolgreichen Teile einer Anforderung durchgeführt, auch wenn während des Vorgangs ein Fehler ausgegeben wird.
2. Seien Sie praktisch: Halten Sie sich an die Richtlinien für die Ratenbegrenzung
Umgang mit dem Fehler „rate limit exceeded“ (Ratenbegrenzung überschritten)
Die Smartsheet-API sieht derzeit eine Ratenbegrenzung von 300 Anforderungen pro Minute je Zugriffstoken vor.
Bestimmte ressourcenintensive Vorgänge wie etwa das Anhängen einer Datei oder das Abrufen des Zellenverlaufs werden mit 10 Anforderungen auf die Ratenbegrenzung angerechnet. Wenn Sie diese Ratenbegrenzung überschreiten, geben die nachfolgenden API-Anforderungen (im Zeitraum von einer Minute) den Statuscode „429 HTTP“ sowie den folgenden JSON-Antworttext aus:
{
“errorCode”: 4003,
“message”: “Rate limit exceeded.”
}
Wir empfehlen, die Integration so zu gestalten, dass sie gut mit diesem Ratenbegrenzungsfehler umgeht. Eine Möglichkeit hierfür ist es, die Integration beim Auftreten des Fehlers für 60 Sekunden in den Ruhezustand zu versetzen und dann erneut zu versuchen, die Anforderung durchzuführen.
Alternativ entscheiden Sie sich vielleicht dafür, ein exponentielles Backoff zu implementieren. Dabei handelt es sich um eine Strategie für die Fehlerbehandlung, bei der Sie die Durchführung einer Anforderung in regelmäßigen Abständen erneut versuchen, wobei die Abstände zwischen einzelnen Versuchen zunehmend größer werden. Das geht so lange, bis entweder die Anforderung erfolgreich oder die festgelegte Anzahl erneuter Versuche erreicht ist.
Vermeiden Sie schnell aufeinanderfolgende Updates
Zusätzlich empfehlen wir Ihnen nachdrücklich, keine schnell aufeinanderfolgenden API-Anforderungen auszuführen, um ein bestimmtes Smartsheet-Objekt innerhalb eines sehr kurzen Zeitraums mehrfach zu aktualisieren.
Wenn Ihre Integration beispielsweise lediglich einmal pro Sekunde eine Anforderung zum Aktualisieren von Zeilen im selben Sheet ausführt, beläuft sich das auf insgesamt 60 Anforderungen pro Minute, was deutlich innerhalb der Richtlinien für die Ratenbegrenzung liegt.
Ein Objekt in solch rascher Folge mehrfach zu aktualisieren, zieht jedoch unter Umständen Speicherfehler nach sich, die sich sowohl auf die Integration als auch auf Ihre Benutzererfahrung auf der Smartsheet-Plattform negativ auswirken.
Um das zu vermeiden, entwickeln Sie Ihre Integration so, dass API-Anforderungen niemals schnell aufeinanderfolgend für dasselbe Smartsheet-Objekt ausgeführt werden. Für die größtmögliche Effizienz sollten Sie Änderungen in Batches zusammenfassen und mithilfe eines Massenvorgangs (z. B. Aktualisieren von Zeilen oder Hinzufügen von Spalten) in einer einzelnen Anforderung übermitteln.
Anforderungen nacheinander ausführen
Wir raten außerdem nachdrücklich davon ab, mehrere API-Anforderungen parallel auszuführen, um ein bestimmtes Smartsheet-Objekt zu aktualisieren. Das führt zu einer eingeschränkten Leistung und aller Wahrscheinlichkeit nach zu Fehlern aufgrund von Speicherkonflikten.
Um das zu vermeiden, entwickeln Sie Ihre Integration so, dass API-Anforderungen zur Aktualisierung eines bestimmten Smartsheet-Objekts immer nacheinander ausgeführt werden: Führen Sie nur eine Anforderung gleichzeitig aus und starten Sie die nächste Anforderung erst, wenn die vorherige Anforderung abgeschlossen ist.
3. Seien Sie smart: Gehen Sie angemessen mit Fehlern um
Eine erfolgreiche API-Anforderung zieht den Statuscode „200 HTTP“ sowie Daten im Antworttext entsprechend dem ausgeführten Vorgang nach sich. Doch was passiert, wenn etwas schiefgeht und kein 200-Code, sondern etwas anderes ausgegeben wird? Ein angemessener Umgang mit Fehlern ist ein wichtiger Bestandteil einer hochwertigen API-Integration.
Wenn eine Smartsheet-API-Anforderung nicht erfolgreich ist, gibt die API den HTTP-Statuscode „4xx“ oder „5xx“ sowie einen JSON-Antworttext aus, der genauere Informationen zu dem aufgetretenen Fehler enthält. Wenn Sie beispielsweise die Anforderung GET Sheet mit einer ungültigen (nicht vorhandenen) Sheet-ID ausführen, gibt die Antwort den HTTP-Statuscode 404 mit dem folgenden JSON-Antworttext aus:
{
“errorCode”: 1006,
“message”: “Not Found”
}
Wann sollten Sie es erneut versuchen?
Damit die Strategie für den Umgang mit Fehlern erfolgreich ist, muss Ihre Integration den Unterschied zwischen Fehlern erkennen, die sich eventuell durch eine erneute Ausführung der Anforderung beheben lassen, und Fehlern, die nicht automatisch erneut ausgeführt werden dürfen.
Der HTTP-Statuscode, der mit einer Antwort ausgegeben wird, ist Ihr erster Hinweis auf das Ergebnis der Anforderung.
Empfehlungen für den Umgang mit Fehlern
Neben dem HTTP-Statuscode sollten Sie außerdem den Smartsheet-spezifischen Fehlercode auswerten, der bei einer nicht erfolgreichen Anforderung im Antworttext ausgegeben wird. Beispiel:
{
“errorCode”: 1006,
“message”: “Not Found”
}
In der API-Dokumentation werden Empfehlungen zur Fehlerbehandlung für jeden Smartsheet-spezifischen Fehlercode angegeben. Wir empfehlen, diese Informationen zu verwenden, um eine Fehlerbehandlungslogik entsprechend der folgenden Richtlinien zu implementieren:
-
Wenn der Fehlercode einen dauerhaften Fehlerzustand anzeigt, wird die Anforderung nicht wiederholt.
-
Wenn der Fehlercode ein Problem anzeigt, das sich beheben lässt, wird die Anforderung erst wiederholt, wenn das Problem behoben wurde.
-
Wenn der Fehlercode ein Problem anzeigt, das sich möglicherweise beheben lässt, wenn die Anforderung nach einiger Zeit wiederholt wird, wird die Anforderung mithilfe eines exponentiellen Backoffs wiederholt.
4. Seien Sie sorgfältig: Implementieren Sie eine Protokollierung
Idealerweise würde Ihre Integration von Anfang an nahtlos funktionieren und Sie müssten nie irgendwelche Fehler beheben.
Doch das ist leider selten der Fall. Wenn Probleme auftreten, muss Ihre Integration in der Lage sein, API-Anforderungen und Antworten zu protokollieren.
Der Zugriff auf die reinen Anforderungen und Antworten (einschließlich detaillierter Informationen zu Fehlercodes und Fehlermeldungen) bei API-Problemen erleichtert die Fehlersuche und beschleunigt die Fehlerbehebung.
Die folgenden Beispiele zeigen die Art der Informationen, die Ihre Anwendung für API-Anforderungen und -Antworten protokollieren sollte:
Anforderung: Verb, URI, Header, Anforderungstext
POST https://api.smartsheet.com/2.0/sheets/4098273196697476/columns
Authorization: Bearer MY_TOKEN
Content-Type: application/json
Anforderungstext:
[
{
"title": "FIRST COLUMN - My New Column",
"index": 0,
"type": "TEXT_NUMBER"
},
{
"title": "FIRST COLUMN - My New Column",
"index": 1,
"type": "TEXT_NUMBER"
}
]
Antwort: HTTP-Statuscode, Antworttext
HTTP-Status: 400 Bad Request
Antworttext:
{
"errorCode": 1133,
"message": "Column titles are not unique among input columns.",
"detail": {
"columnTitle": "FIRST COLUMN - My New Column"
}
}
Oft sind Sie anhand dieser Informationen in der Lage, das Problem selbst zu erkennen und zu lösen. Wenn das nicht der Fall ist, erhalten Sie unter devrel@smartsheet.com weitere Unterstützung. Wir bitten Sie für die Fehlerbehebung um die vorstehenden Informationen zu Anforderung/Antwort.
Sie sollten die Protokollierung der API-Anforderung und -Antwort beim ersten Einrichten der Integration implementieren, da das einen effizienteren Ablauf ermöglicht.
Mit der Erstellung Ihrer Integration beginnen
Egal ob Sie derzeit eine Integration mit Smartsheet entwickeln und erstellen oder bereits zuvor eine Integration erstellt haben: Jetzt ist der richtige Zeitpunkt, um die bewährten Vorgehensweisen einzubinden, die wir in diesem Post vorgestellt haben.
Außerdem empfehlen wir Ihnen, bestmöglich von den Ressourcen und Hinweisen im Smartsheet Developer Portal zu profitieren. Diese sollen Sie dabei unterstützen, schneller mit der Verwendung der Smartsheet-API vertraut zu werden und selbstsicher eine eigene Lösung bereitzustellen.
Abonnieren Sie den Smartsheet-IT-Newsletter, um Tipps, Strategien und Ideen zu erhalten, die darauf abzielen, dass IT-Spezialisten mehr in ihren Unternehmen erreichen können.