Was ist die Zendesk-API?

Eine „Application Programming Interface“ (API) ist ein Tool für die Programmierung von Softwareanwendungen. Stellen Sie sich vor, Sie sitzen im Restaurant und der Kellner bringt das Essen aus der Küche an Ihren Tisch. Die API funktioniert ähnlich: Sie transportiert Daten von einem Ort zum anderen. In der API wird das Gericht als Ressource und der Kellner, der es Ihnen serviert, als Endpunkt bezeichnet. Angenommen, Sie möchten im Restaurant ein bestimmtes Gericht bestellen. Manche Endpunkte legen Ihnen eine Sammlung von Elementen vor, ähnlich wie auf einem Probierteller. Ein Beispiel hierfür in der API ist der Endpunkt „List Users“. Er gibt eine Liste aller Benutzer in Ihrem Zendesk Support-Konto zurück. Andere Endpunkte, zum Beispiel der Endpunkt „Show User“, sind spezifischer und geben nur ein einziges Element zurück.

Sie können die API auch verwenden, um Elemente in Zendesk zu ändern. Stellen Sie sich vor, Sie sagen einem Kellner, wie Sie Ihr Steak haben möchten. Der Koch wird das Steak dann speziell nach Ihrem Wunsch zubereiten. Die API ist ein leistungsstarkes Tool, das viele unserer Kunden nutzen, um zahlreiche Ressourcen in einem einzigen Arbeitsgang zu importieren, Anwendungen zu erstellen, Daten aus externen Quellen abzurufen und andere Aufgaben auszuführen.

Der größte Teil der Referenzdokumentation für die Zendesk-API steht im Bereich „API Reference“ des Zendesk Developer Portals zur Verfügung. In der Referenzdokumentation sind alle verfügbaren Endpunkte beschrieben. Sie können zum Einstieg auch den Zendesk Developer Guide (Englisch) heranziehen. So umfassend die Dokumentation ist, werden wir in diesem Beitrag auf die Dekodierung und Verwendung der API eingehen.

Warum die API verwenden?

Nachdem Sie nun wissen, was die API ist, fragen Sie sich vielleicht, warum Sie das interessieren sollte. Kurz gesagt, mit der API können Sie native oder planabhängige Funktionen, die in der Benutzeroberfläche nicht verfügbar sind, wesentlich schneller hinzufügen, als dies von Hand möglich wäre.

Wenn Sie den Essential- oder den Team-Plan nutzen, können Sie über die API Daten direkt exportieren, ohne auf den Professional-Plan aufzurüsten (der den automatischen Datenexport unterstützt). In ähnlicher Weise können Sie mit der API Ticketdaten für die Berichterstellung abrufen. Die API kann alle Informationen zu einem Ticket zurückgeben, sodass Sie anhand der API-Ausgabe Daten an die Berichtanwendung eines Drittanbieters übermitteln können.

Ein weiterer Vorteil der API ist die Möglichkeit, viele Datensätze rasch in einem Arbeitsgang zu aktualisieren. Während Sie in der Agentenoberfläche beispielsweise immer nur eine Organisation nach der anderen anlegen können, lassen sich mit der API jeweils bis zu 100 Organisationen gleichzeitig erstellen. Auch die maximale Anzahl der Elemente, die Sie in einem Arbeitsgang aktualisieren können, ist bei Verwendung der API deutlich höher. Während in der Oberfläche höchstens 60 Tickets gleichzeitig bearbeitet werden können, sind mit der API bis zu 100 Tickets möglich.

Weitere häufige Aufgaben:

  • Tickets erstellen
  • Migrieren von Ticketdaten aus einem anderen System nach Zendesk
  • Bearbeiten mehrerer Benutzer in einem Arbeitsgang
  • Suchen von Datensätzen
  • Und viele mehr!

Nachdem wir nun geklärt haben, warum Sie die API verwenden sollten, sehen wir uns einmal an, wie Sie eine API-Anforderung erstellen.

Format

Die Zendesk-API gibt Daten in einem schlanken Format namens JSON zurück. Weitere Informationen finden Sie im Zendesk Help Center unter Working with JSON (Englisch). Um die Anzeige der formatierten Daten in einem Webbrowser zu ermöglichen, können Sie eine JSON-Viewer-Erweiterung für Chrome oder Firefox installieren.

JSON sieht folgendermaßen aus:

{
  "posts": [
    {
      "id": 35467,
      "title": "How do I open the safe"
    },
    {
      "id": 35468,
      "title": "How do I reset the combination?"
    },
  ]
}

Ein typischer Endpunkt sieht folgendermaßen aus:

subdomain.zendesk.com/api/v2/users/me.json

Endpunkte können folgende Aktionen ausführen:

  • GET – Elemente abrufen 
  • POST – Bisher nicht vorhandene Elemente erstellen
  • PUT – Vorhandene Elemente aktualisieren
  • DELETE – Elemente entfernen

In einem Browser sind nur GET-Anforderungen möglich. Die übrigen Aktionen können Sie mit Tools wie cURL oder Postman ausführen.

cURL

In der Referenzdokumentation wird in allen Endpunkt-Beipielen cURL verwendet. cURL ist ein Befehlszeilentool, mit dem Sie ohne Browser API-Befehle ausprobieren können. Weitere Informationen finden Sie im Zendesk Help Center unter Installing and Using cURL (Englisch). Sie können cURL für alle vier Aufruftypen verwenden. cURL ist auf einem Mac vorinstalliert, muss unter Windows aber von Hand installiert werden. Anweisungen hierzu finden Sie im Zendesk Help Center unter Installing cURL (Englisch).

Status Ihrer Anforderungen

Nach jeder API-Anforderung werden Sie in einer Antwort informiert, ob sie funktioniert hat. Wenn nicht, enthält die Antwort Hinweise darauf, warum die Anforderung fehlgeschlagen ist. Diese Antworten werden als Statuscodes bezeichnet. Die wichtigsten Codes lauten wie folgt:

  • 200 – Anforderung erfolgreich
  • 400 – Anforderung fehlgeschlagen
  • 409 – Fehler beim Zusammenführen oder Einschränken, Anforderung wiederholen
  • 422 – Nicht verarbeitbare Einheit
  • 429 – Ratenlimit überschritten
  • 500 – Warnung oder vorübergehender Zustand; wenn dieser Code wiederholt zurückgegeben wird, Support kontaktieren

Weitere Informationen zu den Statuscodes finden Sie in der API-Dokumentation unter Response Format (Englisch).

Praxis

Nachdem wir uns mit den Grundlagen der API vertraut gemacht haben, wollen wir nun versuchen, sie zu nutzen, um unsere Tickets zu durchsuchen.

Angenommen, ich arbeite mit dem Team-Plan und habe Stichwörter verwendet, um die Eskalation von Tickets auf verschiedenen Support-Ebenen zu verfolgen. Diese Stichwörter sind escalation_one und escalation_two.

Nun möchte ich einen Bericht generieren, in dem alle Tickets in meinem System aufgeführt sind, die beide Eskalationen durchlaufen haben. Ich habe versucht, eine Ansicht mit diesen Tickets zu erstellen, doch die ist für meine Zwecke nicht geeignet, weil sie keine archivierten Tickets enthält. Wie gehe ich weiter vor?

Antwort: Rufen Sie die Tickets mit der API ab.

Verwenden Sie hierzu den Endpunkt „Search API“. Dieser Endpunkt filtert die archivierten Tickets nicht heraus. Deshalb können Sie ihn verwenden, um eine Liste aller Tickets zurückzugeben, die diese beiden Stichwörter enthalten. Außerdem ist Search API ein einfacher GET-Aufruf, den Sie direkt im Browser ausführen können, wenn Sie in einer anderen Registerkarte des Browsers bei Zendesk Support angemeldet sind. Das Format des Endpunkts „Search API“ sieht folgendermaßen aus:

subdomain.zendesk.com/api/v2/search.json?query={search_string}

Wichtig: Ersetzen Sie „subdomäne“ durch die Subdomäne Ihres Kontos.

Dies Search API ist sehr flexibel und die Query kann alle in der Suchreferenz für Zendesk Support genannten Elemente enthalten. Da wir in unserem Beispiel einfach nach Stichwörtern suchen, verwenden wir in der Suchzeichenfolge lediglich den Parameter „tags“. Wir möchten nach mehreren Stichwörtern suchen und tragen diese im Anschluss an den Parameter „tags“ deshalb durch Komma getrennt ein. Ihr Anruf sollte nun folgendermaßen aussehen:

https://subdomain.zendesk.com/api/v2/search.json?query=tags:escalation_one,escalation_two

Um die Anforderung zu authentifizieren, müssen Sie in einer anderen Registerkarte des Browsers als Agent oder Administrator bei Zendesk Support angemeldet sein.

Wenn Sie diesen Aufruf im Browser ausführen, wird eine Liste der Tickets zurückgegeben, die beide angegebenen Stichwörter enthalten. Die JSON-Ausgabe können Sie dann zur späteren Verwendung speichern.

Herzlichen Glückwunsch! Das war‘s! Die API ist ein leistungsfähiges und sehr vielseitiges Tool. Wenn Sie möchten, können Sie nun tiefer in die Referenzdokumentation und die Dokumentation für Zendesk-Entwickler einsteigen.

Powered by Zendesk