Link Search Menu Expand Document

Ontwikkelen

Het ontwikkelen van je koppeling doe je op onze development-omgeving. Deze omgeving werkt hetzelfde als een echte klantomgeving, maar is gevuld met fictieve data en wordt zowel door onze eigen developers als andere externe developers gebruikt om producten te ontwikkelen.

Aanvraag account webinterface

Het is handig om tijdens het ontwikkelen ook toegang te hebben tot de webinterface. Zo kun je het resultaat van je aanroepen naar de API vergelijken met wat er op de webinterface zichtbaar is.

Het aanvragen van een account voor de webinterface doe je zo:

  1. Log in op onze Topdesk-omgeving
  2. Klik op Een vraag stellen
  3. Vraag een account voor de webinterface aan. Belangrijk: Vermeld het e-mailadres waar het account aan gekoppeld kan worden.

Aanvraag certificaat

Externe applicaties mogen alleen met onze toestemming de API’s aanroepen. Ter authenticatie moeten alle aanroepen naar onze API’s ondertekend zijn met het certificaat van die applicatie. Uit het gebruikte certificaat leiden we af welke applicatie de aanroep doet en voor welke klant het gedaan wordt.

Het aanvragen van een certificaat doe je zo:

  1. Log in op onze Topdesk-omgeving
  2. Klik op Certificaat aanvragen of verlengen
  3. Selecteer Ons API: Nieuw certificaat aanvragen (development)
  4. Voeg als bijlage je .csr-file (certificate signing request) toe

Hoe je een .csr maakt en aan welke eisen die moet voldoen lees je bij CSR Requirements

Certificaat gebruiken

Alle aanroepen naar onze API’s moeten ondertekend worden met het certificaat dat bij die omgeving past, in dit geval je development-certificaat. Hoe je dit goed instelt zal verschillen per framework of platform, we kunnen je hier niet mee helpen.

Hoe je kunt testen of je instellingen goed zijn lees je hier.

Endpoints aanvragen

We hanteren dataminimalisatie op onze API’s. Dat betekent dat je koppeling (op staging- en prodcutieomgevingen) alleen toegang krijgt tot endpoints die je hebt aangevraagd en die door ons goedgekeurd zijn. Op development werkt dat iets anders. Om op development toegang te krijgen tot een endpoint volg je de volgende stappen:

  1. Log in op het Ons API Dashboard
  2. Navigeer naar de koppeling die je aan het ontwikkelen bent
  3. Scroll naar Technical Design en klik op ‘Edit’
  4. Klik op ‘Add usecase’ en beschrijf de usecase waarvoor je een endpoint toe wil voegen. Bijvoorbeeld:
    1. Titel: ‘Synchroniseer cliënten’
    2. Beschrijving: ‘Controleer periodiek of er veranderingen gemaakt zijn aan cliënten en importeert dan de gewijzigde cliënt(en) opnieuw.’
  5. Klik op ‘Add endpoint’
    1. Selecteer het gewenste endpoint, voeg optioneel nog een beschrijving toe waarom dit endpoint nodig is voor deze usecase, en klik op ‘add’
    2. Indien van toepassing verschijnt het model dat dit endpoint oplevert in de lijst van modellen. Klik om het model uit te vouwen en selecteer de velden die je nodig hebt.
  6. Herhaal stap 4 en 5 zo vaak als nodig. Gebruik meerdere usecases om een logische groepering aan te brengen in de benodigde endpoints. Dat helpt ons bij de beoordeling, nu en bij wijzigingen in de toekomst.
  7. Klik naast de kop Technical Design (stukje naar boven scrollen) op ‘Save changes’
  8. De geselecteerde filtering is onmiddelijk van toepassing.

We begrijpen dat dit een hoop werk is als je nog niet zeker weet of je een endpoint nodig hebt. Daarom is het ook mogelijk om alle endpoints beschikbaar te maken voor je koppeling.

  1. Log in op het Ons API Dashboard
  2. Navigeer naar de koppeling die je aan het ontwikkelen bent
  3. Scroll naar Technical Design en klik op ‘Edit’
  4. Zet de knop ‘Allow all endpoints on development’ aan
  5. Klik naast de kop Technical Design op ‘Save changes’
  6. De wijziging is meteen van toepassing.