Let op, om gebruik te kunnen maken van de API heb je de Add-on 'Basic API' of 'Advanced API'. De API is ook beschikbaar in het 'Professional' abonnement

Belangrijk: leest eerst door hoe de API werkt, alvorens je begint met het ophalen van data. Overleg ook met je IT-team alvorens je de API gebruikt.

Wat is een API en hoe werkt het?

Een API (Application Programming Interface) is een set regels en protocollen waarmee verschillende softwaretoepassingen met elkaar kunnen communiceren. Het biedt een manier om toegang te krijgen tot functies en data van een applicatie zonder dat je de interne werking ervan hoeft te kennen. Denk aan een API als een soort tussenpersoon die jouw verzoek naar een applicatie vertaalt, en het antwoord terugstuurt. APIs zijn vooral nuttig voor web-toepassingen, waar een front-end (zoals een website of app) data opvraagt van een server.

APIs maken meestal gebruik van HTTP-verzoeken (zoals GET, POST, PUT, enzovoorts) om gegevens te versturen of op te vragen. Hieronder een overzicht van de belangrijkste HTTP-methoden zoals deze ook in onze API zichtbaar zijn.

GET

Doel: Ophalen van data van de server.
Gebruik: Wordt gebruikt om gegevens op te vragen zonder iets op de server te veranderen.
Voorbeeld: Een website vraagt de details van een gebruiker op via een GET-verzoek naar /user/123, waarbij 123 de ID van de gebruiker is.
Kenmerk: Het is een veilige en idempotente actie (meerdere keren uitvoeren geeft dezelfde uitkomst).

POST

Doel: Nieuwe data aan de server toevoegen.
Gebruik: Wordt gebruikt om een nieuw item te creëren, zoals een nieuwe gebruiker of een nieuwe blogpost.
Voorbeeld: Een POST-verzoek naar /users kan een nieuwe gebruiker aanmaken.
Kenmerk: Niet-idempotent; een tweede POST-verzoek kan een ander resultaat geven dan de eerste (zoals twee gebruikers aanmaken met dezelfde gegevens).

PUT

Doel: Een bestaand item op de server geheel vervangen.
Gebruik: Om een item volledig te updaten; hierbij overschrijft de nieuwe data de bestaande data.
Voorbeeld: Een PUT-verzoek naar /user/123 kan de gegevens van gebruiker 123 volledig overschrijven met nieuwe data.
Kenmerk: Idempotent; hetzelfde PUT-verzoek meerdere keren uitvoeren heeft hetzelfde resultaat.

PATCH

Doel: Een deel van een bestaand item op de server bijwerken.
Gebruik: Om alleen bepaalde eigenschappen van een item te wijzigen zonder alles te overschrijven.
Voorbeeld: Een PATCH-verzoek naar /user/123 kan bijvoorbeeld alleen het e-mailadres van gebruiker 123 aanpassen, zonder de rest van de gegevens te beïnvloeden.
Kenmerk: Ook idempotent (meerdere PATCH-verzoeken met dezelfde wijzigingen geven hetzelfde resultaat).

DELETE

Doel: Een item van de server verwijderen.
Gebruik: Wordt gebruikt om een bestaand item definitief te verwijderen.
Voorbeeld: Een DELETE-verzoek naar /user/123 zal gebruiker 123 verwijderen.
Kenmerk: Idempotent; herhaaldelijk een DELETE-verzoek uitvoeren geeft hetzelfde resultaat na de eerste keer (het item is al verwijderd).

Samenvatting

Methode	Doel	Gebruik	Idempotent?
GET	Data opvragen	Lezen	Ja
POST	Nieuwe data toevoegen	Creëren	Nee
PUT	Hele item vervangen	Updaten	Ja
PATCH	Gedeeltelijk updaten	Delen updaten	Ja
DELETE	Data verwijderen	Verwijderen	Ja

Deze methoden zijn standaard binnen de meeste REST APIs en geven aan wat er met de data moet gebeuren.

TimeChimp API

TimeChimp heeft een eigen API. Bedrijven gebruiken deze vaak om gegevens te wisselen tussen verschillende software systemen. In onze documentatie kan je zien welke data je kan ophalen, bewerken of verwijderen: https://v2.api.timechimp.com/index.html#overview

Stappenplan om data op te halen

Ga naar de website van Postman en maak een account aan, dit is gratis (https://www.postman.com).
Creëer een nieuwe 'workspace'.
Creëer een nieuwe collectie.
Voeg een request toe.
Voeg in de request onder het kopje 'headers' een api key toe. De key maak je aan in TimeChimp via het tandwiel icoontje > API. Kopieer de key en voeg deze toe onder het kopje 'Key'. Geeft als naam van de key 'api-key' (geen api-x-key).
Voeg in het veld 'Value' de api key uit je organisatie toe
Plaats in the URL the data op die je wilt ophalen, je gebruikt hier de GET-methode voor. In de URL plaats je altijd een link naar onze API documentatie plus de dataset die je wilt ophalen. In het voorbeeld wil ik dus klanten ophalen dus de url-link moet zeggen: https://v2.api.timechimp.com/customers.

Dit zou er als volgt uit moeten zien:
Wanneer je alles hebt toegevoegd en in de URL hebt toegevoegd welke data je wilt ophalen, druk op de knop 'Send'.
Je haalt nu gegevens op, deze komen in zogenoemde JSON 'taal' onderaan het scherm zoals hieronder te zien is:
deze gegevens kan je opslaan in een JSON-bestand via de 3 puntjes rechts (save respond to file):

Transformeren naar Excel

Stap 11) Open Excel

Stap 12) Klik op 'gegevens ophalen (via power query)

Stap 13) Klik op JSON en selecteer het eerder opgeslagen JSON bestand

Stap 14) Klik op 'Result [List]'

Stap 15) Klik op converteren naar tabel, linksboven in het scherm

Stap 16) Klik op het splitsingteken en selecteer alle velden die je mee wilt nemen

Stap 17) Nu zie je alle gegevens die je kan inladen als onderstaand. Let op: Sommige velden dienen opgehaald te worden via het in Stap 16 getoonde splitsingteken zoals in de tweede afbeelding onder deze tekst

Stap 18) Klik op sluiten & laden linksboven in het scherm