Was die TOPdesk-API liefert und was nicht

Die offizielle Dokumentation der TOPdesk-API finden Sie auf developers.topdesk.com. Die Angaben dort sind solide, und die API verhält sich wie erwartet. Einige Eigenheiten bemerken Sie aber erst, wenn Sie eine Weile damit gearbeitet haben, und sie können Ihre Pläne für das Reporting durchkreuzen. Aufgefallen sind sie bei der Entwicklung eines Dashboards auf Basis dieser API.

Was die API ohne Weiteres liefert

Am einfachsten ist es bei Incidents. Sie bekommen sie mit Kategorie und Unterkategorie, Status, Priorität, Level, Bearbeitergruppe, Bearbeiter, Anmeldedatum, dem Datum der Fertigstellung und dem des Schließens sowie den SLA-Feldern. Damit können Sie Eingang, Durchlaufzeit und SLA-Einhaltung pro Priorität auswerten und sehen, wie lange der älteste Incident schon offen ist.

Changes und die zugehörigen Aktivitäten liefert die API ebenfalls, genau wie operative Aktivitäten, Assets mit Typ, Standort und Status sowie Wissenseinträge mit ihrem Status und der Angabe, ob sie im Self Service Portal sichtbar sind. Bearbeiter lassen sich einschließlich ihrer Berechtigungsgruppen abrufen, und daran sehen Sie, welche Konten eine kostenpflichtige Lizenz belegen. Ob ein solches Konto auch genutzt wird, lässt sich daran nicht ablesen; dafür führen Sie Daten aus mehreren Modulen zusammen.

Was die REST-API nicht liefert: die Vorgeschichte

Die fehlende Vorgeschichte ist der wichtigste Punkt, und an ihr scheitern die meisten Pläne. Die REST-API liefert Ihnen den aktuellen Zustand eines Incidents. Sie sehen, welcher Bearbeitergruppe und welchem Bearbeiter er gerade zugewiesen ist und welchen Status er hat.

Frühere Bearbeitergruppen liefert die REST-API dagegen nicht. Ob Incident 4711 zuerst beim 1st Level lag, danach elf Tage beim Netzwerkmanagement und anschließend wieder zurückging, sehen Sie in TOPdesk im Tab „Vorgeschichte“ der Karte. Über die REST-API sind diese Übergaben (Stand September 2026) nicht abrufbar.

Für Ihre Berichte heißt das, dass sich die Frage „Wo bleibt Arbeit liegen?“ mit der REST-API allein nicht beantworten lässt. Gerade diese Frage stellt das Management aber meist, denn an diesen Stellen verlängert sich die Durchlaufzeit.

Mit der REST-API bleibt nur, die Vorgeschichte selbst aufzuzeichnen, und Ihre Zeitleiste beginnt dann erst mit der Anbindung. Für die Zeit davor lässt sie sich nachträglich nicht mehr erstellen. Wer eine solche Zeitleiste braucht, sollte deshalb früh mit der Aufzeichnung beginnen, denn sie reicht mit jedem Monat weiter zurück.

Pfade unterscheiden sich je nach Lizenz und Version

Die Incident-API ist überall dieselbe. Für die übrigen Teile der API gilt das nicht. Welche Endpunkte für Changes, Assets und Wissenseinträge verfügbar sind, hängt von den Modulen in Ihrer Lizenz und von Ihrer TOPdesk-Version ab.

Auf Annahmen können Sie sich dabei nicht verlassen. Hat eine Umgebung kein Assetmanagement, gibt es diesen Pfad nicht, und Sie erhalten statt einer leeren Liste eine Fehlermeldung. Prüfen Sie deshalb zuerst in Ihrer eigenen Umgebung, welche Pfade verfügbar sind, statt von der allgemeinen Dokumentation auszugehen.

Der Unterschied zwischen 401 und 403

Wer die beiden Codes auseinanderhält, spart bei der Fehlersuche unter Umständen Stunden. Ein 401 bedeutet, dass TOPdesk die Anmeldung nicht akzeptiert, etwa wegen eines falschen Benutzernamens, eines widerrufenen Anwendungstokens (in älteren TOPdesk-Versionen: Anwendungskennwort) oder eines Kontos ohne die Berechtigung REST-API. Bei einem 403 sind Ihre Zugangsdaten in Ordnung, aber es fehlt die nötige Berechtigung, weil der Bearbeiter keine Leserechte für dieses Modul hat.

Bei einem 403 hilft es also nicht, das Anwendungstoken zu ersetzen. Prüfen Sie stattdessen die Berechtigungsgruppen dieses Bearbeiters und sehen Sie nach, welches Modul fehlt. Bei der Entwicklung von AureaDesk wurden 401 und 403 einmal verwechselt, was einen ganzen Nachmittag gekostet hat.

Paginierung in großen Umgebungen

In einer Umgebung mit ein paar tausend Incidents fällt die Paginierung nicht auf. Große, stark genutzte Umgebungen können darauf anders reagieren, als ein kleiner Test vermuten lässt. Der Abruf bleibt dann hängen, oder Ihnen fehlt unbemerkt ein Teil der Daten.

Testen Sie deshalb nicht nur in Ihrer eigenen Umgebung. Was bei ein paar hundert Incidents funktioniert, kann sich bei Zehntausenden anders verhalten, und oft zeigt sich das erst, wenn die Anbindung schon im Einsatz ist.

Auch der erste vollständige Abruf ist aufwendiger, als Sie vielleicht erwarten. Wer eine große Liste auf einem kleinen Server auf einmal abruft, stößt an Speichergrenzen. Teilen Sie den Abruf deshalb in kleinere Schritte auf.

Was Sie für die Anbindung brauchen

Eine spezielle Integrationslizenz brauchen Sie derzeit nicht; prüfen Sie das anhand Ihres eigenen TOPdesk-Vertrags. Sie legen in TOPdesk einen eigenen Bearbeiter als API-Konto für die Anbindung an, mit API-Zugriff und Leserechten für die Module, deren Daten Sie abrufen möchten. Für diesen Bearbeiter erstellen Sie ein Anwendungstoken, mit dem sich die Anbindung anmeldet.

Nutzen Sie dafür einen separaten Bearbeiter und nicht das Konto einer Kollegin oder eines Kollegen. In den Logs erkennen Sie so, dass der Zugriff von der Anbindung kam und nicht von einer Person. Die Anbindung können Sie dann auch abschalten, ohne dass jemand den eigenen Zugang verliert.

Beschränken Sie die Rechte auf das Nötigste. Berichte kommen ohne Schreibzugriff auf Daten aus, und eine Anbindung, die nur liest, kann in Ihrem TOPdesk nichts ändern. Auch das Lesen läuft über die API. Informieren Sie deshalb die Person, die Ihr TOPdesk verwaltet, über die Anbindung.

Ein Dashboard auf Basis der REST-API

Mit der REST-API lässt sich ein vollwertiges Dashboard aufbauen, es kostet aber mehr Zeit, als es nach einem ersten Test scheint. Wollen Sie wissen, wo Arbeit liegen bleibt, müssen Sie die Vorgeschichte selbst aufzeichnen. Was verfügbar ist, prüfen Sie für jede Umgebung einzeln, statt sich auf die allgemeine Dokumentation zu verlassen. Nach einer neuen TOPdesk-Version sehen Sie erneut nach, welche Pfade es gibt.