API

Om de Roosterplanning API te gebruiken is specialistische technische kennis vereist.

Roosterplanning heeft een uitgebreide API om data uit te lezen, data te sturen en acties uit te voeren. Deze API kan door elke gebruiker, voor zover de rechten van de gebruiker dat toelaten, gebruikt worden.

Benodigdheden

Een gebruiker (“gebruiker A”) om in te loggen in Roosterplanning, met rechten om de API documentatie te bekijken. De klant maakt deze gebruiker aan, C-quential kent de gebruiker de rechten toe voor de API.
Een gebruiker (“gebruiker B”) om in te loggen op de API. Dit kan dezelfde gebruiker zijn als gebruiker A.
Een client id en client secret. Deze kunnen door de contactpersoon voor Roosterplanning via de Support Desk aangevraagd worden. Indien gewenst kan voor extra veiligheid de client aan een specifieke gebruiker gekoppeld worden. Andere gebruikers kunnen dan geen gebruik maken van de API met deze client.
Het is handig om de “clone”-omgeving te gebruiken voor het testen van de API. Er is geen “sandbox”-modus beschikbaar op de productieomgeving.

Basiswerking Roosterplanning API

Hier leggen we enkele bijzonderheden van de Roosterplanning API uit.

Datamodel

Roosterplanning is een omvangrijk product, met veel modules en opties. Er is ook een lange historie van hoe het product tot stand is gekomen. Dit resulteert in een uitgebreid datamodel dat lastig samen te vatten is in een API documentatie. We adviseren daarom om bij specifieke toepassingen te overleggen over mogelijke oplossingen.

Includes

De API maakt gebruik van “includes”, deze vind je ook terug in de API documentatie. Includes zorgen ervoor dat je meerdere lagen uit het datamodel kan ophalen in één verzoek. Hiermee proberen we zoveel mogelijk te vermijden dat je voor een kleine hoeveelheid data meerdere API verzoeken moet uitvoeren. Zo wordt het bijvoorbeeld mogelijk in één verzoek alle diensten van de huidige gebruiker van vandaag op te halen, in plaats van dat eerst de dienstverbanden, dan per dienstverband de aanstellingen, en dan per aanstelling de diensten opgehaald moeten worden.

Hulp

Heb je hulp nodig met het gebruik van de API? De contactpersoon voor Roosterplanning kan dit via de Support Desk aanvragen.

Beginnen

Log met gebruiker A in in Roosterplanning. Onder het menu “Overig”, vind je de “Nieuwe API documentatie”.

De API documentatie is in het Engels geschreven.

We geven de documentatie binnen Roosterplanning weer d.m.v. Swagger UI. Voor de meest recente versie van de documentatie, raden we aan om deze documentatie te gebruiken. Je kunt de achterliggende API specificatie ook downloaden om in andere tooling te gebruiken. De downloadlink staat direct onder de titel.

Inloggen

Om in te loggen, druk rechts, direct onder de header, op “Authorize”:

Vul in de popup de gebruikersnaam van gebruiker B, het wachtwoord van de gebruiker, en de client id en secret in:

Druk vervolgens op Authorize. Als alles goed gaat, zie je het volgende scherm:

Je kunt nu het “Authorizations”-scherm sluiten en de verschillende API endpoints (of API calls) aanroepen.

Controle

Om te testen of alles correct werkt, kun je de “Get user” API uitvoeren (“/users/{id}”). Gebruik de speciale id “me” en haal alle “includes” weg. De API zou een antwoord terug moeten geven dat lijkt op onderstaande.

{
  "data": {
    "id": 1895,
    "username": "gebruiker B",
    "phone": null,
    "mobilePhone": null,
    "email": "info@example.org"
  }
}

Concreet voorbeeld: alle diensten van de huidige gebruiker van 3 januari 2024, met de diensttijden

In dit voorbeeld zullen we een Bash CLI gebruiken om de verzoeken te doen.

Vraag eerst een token op. Gebruik een Basic Authorization header met een base64 encoded client id en client secret met een dubbele punt ertussen. In onderstaande voorbeeld zijn de volgende gegevens gebruikt:

Client ID: 10001
Client secret: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN
Gebruikersnaam: gebruiker B
Wachtwoord: notanactualpassword

curl 'https://<klant>.clone.c-quential.nl/laravel/api/v2/oauth/token' -X POST \
  -H 'Accept: application/json' -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic MTAwMDE6YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQkNERUZHSElKS0xNTg==' \
  --data-raw 'grant_type=password&username=gebruiker+B&password=notanactualpassword'

Bij gebruik van correcte gegevens, krijg je een respons als onderstaand:

{
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIzIiwianRpIjoiOWIxMDc3MTc3ODhlNzA2MDI1MzIxN2E2MTNmMWJjNGM2YTBlMTE4NzI2ZGU4OTkyM2VmY2M0ZmE2NjM4NGE0NWVhZWFjODJjMzNhY2ViNTIiLCJpYXQiOjE3MDQyODI4MTAuNjc1Njk5LCJuYmYiOjE3MDQyODI4MTAuNjc1NywiZXhwIjoxNzA0MzY5MjEwLjA5NTgzMywic3ViIjoiMzQ3Iiwic2NvcGVzIjpbXX0.OAvV1Baxmrppw6PYJ8yki0n2_p1C05CmsUkjLBp3IqWroL_8BisMwelLZWKuM7b3Z6NoWdVF3pQmznYDOhIOgjCdQPgZa8QPzVgt2Dj9RsGvR3dExQO4vrYh5woW9hMnu1cho-HVIb8Z4iQRz0KeEhwDlcJBaOIyFCPPqTjKuAF6UjNJqTE7-4sjezhj63f5TjK5tcqu_2JuVkvctjNQcQ2PFm59jdBvjPEHUeVRStr_6ppYGxLZ4sXAZORh0RLUNDyTTr0cRso-FYvf0qxiffpf3CPWmoY7xv-H_CMbSUWTo7fo0M5K4Slz9sl2kguwDytP46W6FfX5sHEOBmiWjh43DVjpj8tjO0-fCOiQbE7S41tnNHOBNEnCZ6UN-Wx4VpAN93b5r91kGXqyVv-d5ebegRJ4mT2HziCYwfFhysEQkQqEDdbX-h9RalY-ijUXfnsvFOOff8X0gTjeXMjxr1EuYZL-3_w0uEYziAHhYKvhDMvD252duKIsuDI7ncmKq4PThaEavQmbO2663ZGDRtAr4yeM7xBT4PtBOLqYd-VAQBMcobM3Q8hpB21M0fe8QPUYbTulMO3vP2PYQDYN0WdDxGpFVno8Zm8aH7HCry7YaxqkHQSqObYclniWhgFRM5bcErlVfGFHILOT3f9yae1goqkuz3Gw1pve0KgYf2g",
    "refresh_token": "def502005cdbecd44a4e8b1e4c8182dc9e5d7895f008c8aaa57360bdb557bddf3b23cbd3c565146b86aaef7578a28ce2fbb4d219b52d45c8c4aa1ed488089f4249181049a548e4ecafd9b2f4b8f04d8fd42689255c2a5685cf1bb385b882ed6fa4676b97ce2d9bc668ab858a1f970629983d2b028fa8e07321a0a68c6e0ef4bf7912ccc596f7ac140a0dd7274f7f85bc10f6210af0f30020dc6c6642c452c36e608f8f28c5a834a7292cd86fd6f29ff88a88a257ba260a2afa088fbe5dbca63d6a8aeee3a9b62e6da195ef2ca93653615748748583a110ee2acb003f6ef51ae4406080c19428268951a0849cdabca12f3228069e9c7d6ef9faeac313f4d084ce6ccb0ca3728decb6b456223f3883cc3d0f76b4cb8d8200d17747d944b59cc7078c6ff21d007b41955be25e770bc242f52a903bed2963ed3eb244a06d68dc7fe0b1a64544dc7db9171275a8f37b53acdcfbbbd227d36d44f0841f4f38d0e28013aa4cb6"
}

De access_token kan nu gebruikt worden in een Bearer Authorization header voor volgende verzoeken. In dit geval zullen we de diensten van 3 januari 2024 ophalen:

Een voorbeeldrespons is dan: