Wat de TOPdesk-API wel en niet teruggeeft

De officiële documentatie van de TOPdesk-API staat op developers.topdesk.com. De documentatie is goed verzorgd, en de API doet wat je verwacht. Een paar dingen merk je pas als je er langer mee werkt, en die kunnen je plannen voor rapportage flink veranderen. Ze vielen op bij het bouwen van een dashboard op de API.

Wat je eenvoudig uit de API haalt

Meldingen zijn het eenvoudigst. Je haalt ze op met categorie en subcategorie, status, prioriteit, lijn, behandelaarsgroep, behandelaar, aanmelddatum, de datums van gereedmelden en afmelden, en de SLA-gegevens. Daarmee kun je de instroom, de doorlooptijd en de SLA-naleving per prioriteit laten zien, en ook hoe lang de oudste openstaande melding al ligt.

Ook wijzigingen en wijzigingsactiviteiten kun je ophalen, net als operationele activiteiten, assets met type, locatie en status, en kennisitems met status en of ze zichtbaar zijn in de Self-Service Portal. Behandelaren kun je opvragen met de bijbehorende rechtengroepen, en daaraan zie je welke accounts een betaalde licentie gebruiken. Of zo'n account ook wordt gebruikt, lees je er niet aan af; daarvoor breng je gegevens uit meerdere modules samen.

Wat de REST-API niet teruggeeft: de geschiedenis

Dit is het belangrijkste punt, want hier gaan de meeste plannen mis. Met de REST-API haal je de huidige stand van een melding op. Je ziet welke status hij heeft en bij welke behandelaarsgroep en behandelaar hij ligt.

Eerdere statussen en behandelaarsgroepen van de melding krijg je niet terug. Je kunt niet opvragen dat melding 4711 eerst bij de eerste lijn lag, toen elf dagen bij netwerkbeheer, en daarna terugkwam. In TOPdesk zie je zulke overdrachten wel op het tabblad Geschiedenis van de kaart, maar de REST-API levert ze op het moment van schrijven (september 2026) niet uit.

Met alleen de REST-API kun je niet laten zien waar werk blijft liggen. Het management vraagt daar meestal naar, omdat de doorlooptijd op die plekken oploopt.

Met alleen de REST-API is de enige mogelijkheid om de geschiedenis zelf bij te houden, en dan begint je tijdlijn pas op het moment dat je koppelt. Over de periode voor het koppelen kun je hem achteraf niet meer opbouwen. Wil je zo'n tijdlijn, begin er dan vroeg mee, want hoe langer hij loopt, hoe meer je eraan hebt.

De paden verschillen per licentie en per versie

De meldingen-API is bij iedereen hetzelfde. Welke endpoints er voor wijzigingen, assets en kennisitems zijn, hangt af van de modules in je licentie en van je TOPdesk-versie.

Je kunt er dus niet van uitgaan dat een pad bestaat. Heeft een omgeving geen Asset Management, dan ontbreekt het pad voor assets, en geeft de aanroep een foutmelding waar je een lege lijst zou verwachten. Controleer eerst in je eigen omgeving welke paden beschikbaar zijn, en ga daarbij niet af op de algemene documentatie.

401 en 403 betekenen niet hetzelfde

Als je het verschil kent, kan dat uren zoeken schelen. Bij een 401 laat TOPdesk je niet inloggen. Dat kan komen door een verkeerde gebruikersnaam of een ingetrokken applicatietoken (in oudere TOPdesk-versies heette dat applicatiewachtwoord). Ook als het account het recht REST-API mist, krijg je een 401. Een 403 betekent dat je gegevens kloppen, maar dat je dit niet mag, omdat de behandelaar geen leesrechten op die module heeft.

Bij een 403 hoef je het applicatietoken dus niet te vervangen. Kijk in de rechtengroepen van die behandelaar welke module ontbreekt. Tijdens de bouw van AureaDesk zijn de twee codes een keer verwisseld, en dat kostte een middag.

Paginering bij grote omgevingen

Bij een paar duizend meldingen merk je hier niets van, maar in grote en drukke omgevingen gedraagt paginering zich soms anders dan een kleine test doet vermoeden. Het ophalen loopt dan vast, of je mist een deel van de gegevens.

Test niet alleen op je eigen omgeving. Een koppeling die bij een paar honderd meldingen goed werkt, kan bij tienduizenden anders uitpakken, en vaak merk je dat pas als hij al in gebruik is.

De eerste keer haal je alles op, en ook dat is zwaarder dan je zou verwachten. Op een kleine server loop je tegen geheugengrenzen aan als je een grote lijst in een keer opvraagt. Haal de gegevens daarom in delen op.

Wat je nodig hebt om te koppelen

Een speciale integratielicentie heb je op het moment van schrijven niet nodig; kijk dit na in je eigen TOPdesk-contract. Je maakt in TOPdesk een aparte behandelaar aan als API-account voor de koppeling, met API-toegang en leesrechten op de modules die je wilt uitlezen. Daarbij maak je een applicatietoken aan, en daarmee logt de koppeling in.

Gebruik daarvoor dus niet het account van een collega. Met een apart account zie je in de logs eenvoudig terug wat de koppeling heeft gedaan, en kun je het uitschakelen wanneer je wilt zonder dat iemand zijn eigen toegang kwijtraakt.

Houd de rechten zo beperkt mogelijk. Voor rapportage heb je geen schrijfrechten op gegevens nodig, en een koppeling die alleen leest, kan niets in je TOPdesk veranderen. Laat de beheerder van je TOPdesk wel weten dat de koppeling er is, want ook lezen gaat via de API.

Een dashboard op de REST-API

Met de REST-API kun je een goed werkend dashboard bouwen, maar het kost meer tijd dan het na een eerste test lijkt. Om te zien waar werk blijft liggen, moet je de geschiedenis zelf bijhouden. Verder controleer je per omgeving wat er beschikbaar is, zonder op de algemene documentatie te vertrouwen. Na een nieuwe TOPdesk-versie kijk je opnieuw welke paden er zijn.