Inleiding
De RESTful API van het platform maakt het mogelijk om gegevens uit te wisselen tussen het platform en externe systemen. Je kunt gegevens opvragen, toevoegen, wijzigen of verwijderen — bijvoorbeeld om berichten automatisch te plaatsen of evenementen via een ander systeem te beheren.
In dit artikel lees je hoe de RESTful API werkt, hoe je de API-documentatie via Swagger bekijkt, hoe authenticatie werkt en wat je kunt doen als je problemen ervaart.
Het gebruik van de API vereist technische kennis van REST en datamodellering. Het correcte gebruik en het beheer van de bijbehorende data is altijd de verantwoordelijkheid van de klant.
Hoe werkt de RESTful API?
Met de RESTful API kun je via vier soorten verzoeken communiceren met het platform. Elk verzoektype heeft een vast doel:
- GET: gegevens ophalen uit het platform.
- POST: nieuwe gegevens toevoegen aan het platform.
- PATCH: bestaande gegevens wijzigen.
- DELETE: gegevens verwijderen.
De volledige set aan beschikbare verzoeken is automatisch gedocumenteerd via Swagger. Swagger is een tool die op basis van de API zelf een interactieve documentatiepagina genereert, waarin je verzoeken ook direct kunt uitproberen.
Welke gegevens kun je via de API opvragen?
Via de API zijn onder andere de volgende gegevens beschikbaar:
- Gebruikersinformatie
- Documenten
- Berichten
- Groepsinformatie
- Evenementen
Hiermee kun je bijvoorbeeld berichten automatisch plaatsen of verwijderen op vaste tijden, of evenementen plannen en bijwerken vanuit een ander systeem.
De API-documentatie openen via Swagger
Zodra de api-docs-pagina beschikbaar is op je platform, kun je deze openen in de browser om alle beschikbare verzoeken te bekijken en te testen.
- Ga naar de URL van je platform (bijvoorbeeld https://my.plek.co).
- Voeg
/api-docstoe aan de URL, zodat deze er bijvoorbeeld zo uitziet: https://my.plek.co/api-docs. -
De Swagger-documentatiepagina opent en toont alle beschikbare verzoeken, gegroepeerd per onderwerp.
- Vouw een verzoek open en klik op Try it out om het verzoek direct uit te proberen.
Gebruik Swagger om verzoeken eerst uit te proberen voordat je ze in een productie-integratie gebruikt. Zo zie je direct welke parameters verplicht zijn en welke respons je terugkrijgt.
Authenticatie met client-ID en client-Secret
Elk API-verzoek moet authenticatiegegevens meesturen. Zonder geldige authenticatie wordt het verzoek geweigerd.
De authenticatiegegevens bestaan uit twee waarden:
- Client-ID: een uniek ID dat je platform identificeert.
- Client-Secret: een unieke API-key die als wachtwoord dient.
Beide waarden stel je in via de hoofdconfiguratie op de platform VHost. Een beheerder met de juiste rechten kan deze gegevens aanmaken en beheren.
Behandel je client-Secret als een wachtwoord. Deel deze nooit publiek (bijvoorbeeld in code-repositories of berichten) en bewaar deze alleen op een veilige plek. Bij vermoeden van lekken: laat de gegevens direct vernieuwen.
Problemen oplossen
Mijn verzoek geeft een 401- of 403-fout terug
- Controleer of de client-ID en client-Secret correct zijn meegestuurd in de header van het verzoek.
- Controleer of de gegevens nog actief zijn in de hoofdconfiguratie van het platform.
- Controleer of de gebruiker waarmee je werkt voldoende rechten heeft voor het opgevraagde gegeven.
De pagina /api-docs is niet bereikbaar
- Controleer of je de juiste VHost-URL gebruikt (zonder typefout in het domein).
- Controleer of de api-docs-pagina is geactiveerd op je platform. Neem bij twijfel contact op met support.
Mijn POST- of PATCH-verzoek wordt geweigerd
- Controleer of de inhoud van je verzoek voldoet aan het verwachte datamodel (zie de Swagger-documentatie).
- Controleer of alle verplichte velden zijn meegestuurd.
- Test het verzoek eerst via Swagger om de exacte foutmelding te zien.
Ik ben mijn client-Secret kwijt
Een client-Secret is na aanmaak niet opnieuw op te vragen. Stuur een e-mail naar support.plek@bcs-hr.com om een nieuwe te laten genereren. Neem ook contact op met support als het probleem aanhoudt na het doorlopen van bovenstaande stappen.