★ Een eenvoudige uitleg over de API
Wat is de API?
De Application Programming Interface (API) kan worden gebruikt om opdrachten of gegevens naar aNewSpring te sturen of om gegevens op te vragen. Dit kan je helpen om je resources in aNewSpring (zoals gebruikers, uitvoeringen, inschrijvingen, etc.) te beheren en synchroon (up-to-date) te houden met je eigen database.
Met dit artikel proberen we uit te leggen hoe de API werkt, zonder te veel technisch jargon te gebruiken. het artikel is niet bedoeld voor ontwikkelaars, maar voor andere aNewSpring-gebruikers die willen begrijpen wat de API voor ze kan betekenen.
Ben je een ontwikkelaar? We hebben hier specifiekere technische informatie over de API beschikbaar.
API calls
Een API call kan een opdracht of een verzoek om gegevens zijn. Onze API ondersteunt POST requests en GET requests.
POST requests
Je kunt de API de opdracht geven om bepaalde acties uit te voeren die je anders handmatig als beheerder zou doen. Dit soort opdrachten noemen we POST requests en ze kunnen ook gegevens bevatten die in aNewSpring opgeslagen moeten worden.
Aan de hand van een POST geeft de API een respons (antwoord) terug aan het externe systeem waarin staat aangegeven dat de opdracht succesvol is uitgevoerd of dat het is mislukt (en waarom).
Voorbeeld:
POST /subscribe/{userID}/{courseID}
Als de integratie deze POST naar de API van aNewSpring stuurt, betekent dit dat je de API de opdracht geeft om een gebruiker (met de externe ID op de plaats van userID) in te schrijven voor een uitvoering (met de externe ID op de plaats van courseID).
De API voert dan deze actie uit, mits de gebruiker en uitvoering met de betreffende externe ID's ook daadwerkelijk bestaan.
GET requests
Je kunt de API ook om gegevens vragen. Dit noem je GET requests.
Als de GET mislukt (er is bijvoorbeeld geen gebruiker met de betreffende externe ID), dan zal de API het externe systeem laten weten waarom de gegevens niet verstuurd konden worden.
Voorbeeld:
GET /getSubscriptions/{userID}
Als de integratie deze GET naar de API van aNewSpring stuurt, zal de API een respons geven met een lijst van uitvoeringen waar de gebruiker (met de externe ID op de plaats van userID) op dat moment een inschrijving voor heeft.
Als je de API wilt gebruiken om resultaten van uitvoeringen op te vragen, kun je ook overwegen om in plaats daarvan Webhooks te gebruiken.
Dit kan veel API calls schelen, omdat de gegevens direct naar je systeem worden verzonden wanneer ze beschikbaar zijn. Als je hiervoor de API zou gebruiken, zou je systeem alle gegevens voor veel deelnemers regelmatig (bijvoorbeeld dagelijks of elk uur) moeten opvragen. De gegevens in het externe systeem zijn dan niet per direct bijgewerkt, maar daar zit dan een vertraging in.
Externe ID's
De meeste resources waarnaar je verwijst met API calls (zoals uitvoeringen, gebruikers, etc.) hebben een extern ID nodig in aNewSpring, omdat de API op die manier kan identificeren waar de API call op moet worden uitgevoerd. Sommige API calls maken geen gebruik van externe ID's, maar stellen zelf een extern ID in. In dit artikel vind je meer informatie over alle externe ID's en hoe je ze kunt instellen.
Als alternatief voor externe ID's, ondersteunen veel API calls ook automatisch gegenereerde UID's.
Er is een technisch overzicht van alle mogelijke API calls, een voorbeeld van de output en mogelijke response codes in onze API documentatie.
Wat is er precies mogelijk?
De API kan worden gebruikt om de resources in aNewSpring te beheren. Dit wordt hieronder (per resource) samengevat. De API is ook nodig als je Single Sign-On wilt inrichten.
Gebruikers
Deze gegevens kun je ophalen (GET):
- de gebruikersgegevens en rollen van bestaande gebruikers
- of een gebruiker al bestaat in aNewSpring
Deze opdrachten kun je geven (POST):
- een extern ID aan een bestaande gebruiker toekennen
- een nieuwe gebruiker toevoegen
- gegevens van een bestaande gebruiker bijwerken
- een gebruiker verwijderen
- auteurs en/of ontwerpers aan contentbibliotheken koppelen en ontkoppelen
Gebruikersgroepen
Deze gegevens kun je ophalen (GET):
- of een gebruikersgroep al bestaat
- of een gebruiker al in een groep zit
- de gebruikers in een groep
Deze opdrachten kun je geven (POST):
- een nieuwe gebruikersgroep toevoegen
- een groep bijwerken: de naam van een bestaande groep veranderen of verplaatsen door de parent groep te veranderen
- gebruikers toevoegen aan een groep
- gebruikers verwijderen uit een groep
- een gebruikersgroep verwijderen
Subomgevingen
Deze opties zijn alleen van toepassing als subbeheer is aangezet voor je leeromgeving.
Deze opdrachten kun je geven (POST):
- events en subomgevingen (ont)koppelen
- gebruikersgroepen en subomgevingen (ont)koppelen
- templates en subomgevingen (ont)koppelen
- gebruikers en subomgevingen (ont)koppelen
Inschrijvingen
Deze gegevens kun je ophalen (GET):
- of een gebruiker al is ingeschreven voor een specifieke uitvoering
- alle inschrijvingen van een specifieke gebruiker
- alle resultaten van een specifieke gebruiker
In plaats van resultaten via de API op te vragen, kan het beter zijn om Webhooks te gebruiken.
Deze opdrachten kun je geven (POST):
- een gebruiker inschrijven voor een uitvoering
- de details van de inschrijvingen aanpassen (zoals de start- en verloopdatum)
- een gebruiker uitschrijven uit een cursus
- een score registreren voor een externe activiteit in een specifieke uitvoering voor een specifieke gebruiker
Templates en uitvoeringen
Deze gegevens kun je ophalen (GET):
- een lijst met bestaande gepubliceerde templates die een extern ID hebben (en niet gearchiveerd zijn)
- een lijst met uitvoeringen van een specifieke template
- details van een specifieke uitvoering
- een lijst met deelnemers die zijn ingeschreven voor een specifieke uitvoering
- een lijst met deelnemers die zijn gekoppeld aan een specifieke begeleider van een specifieke uitvoering
- een lijst met begeleiders die zijn gekoppeld aan een specifieke deelnemer van een specifieke uitvoering
Deze opdrachten kun je geven (POST):
- een nieuwe uitvoering aan een specifieke template toevoegen
- de instellingen van de uitvoering aanpassen, inclusief het koppelen van begeleider- en observatorgroepen
- de rechten van begeleiders van een specifieke uitvoering aanpassen
- aanpassen welke begeleider een specifieke activiteit mag beoordelen
- begeleiders en deelnemers (ont)koppelen
- een uitvoering verwijderen
- een template kopiëren
Agendapunten
Deze gegevens kun je ophalen (GET):
- of een agendapunt al bestaat
Deze opdrachten kun je geven (POST):
- een nieuw agendapunt toevoegen aan een specifieke uitvoering
- een agendapunt aanpassen
- agendapunten verwijderen
Toegangscodes
Deze gegevens kun je ophalen (GET):
- of een toegangscodegroep al bestaat
- of een toegangscode al bestaat
Deze opdrachten kun je geven (POST):
- een nieuwe toegangscodegroep toevoegen
- nieuwe toegangscodes genereren
- een specifieke toegangscode toevoegen
- een specifieke toegangscode toevoegen en aan een bestaande deelnemer koppelen
- een toegangscode verwijderen
- een toegangscodegroep verwijderen
Events
Deze opdrachten kun je geven (POST):
- een nieuw event toevoegen
- de gegevens en instellingen van een bestaand event aanpassen
- begeleiders en events (ont)koppelen
- een event koppelen aan een specifiek event activiteit van een specifieke uitvoering
- events ontkoppelen
Profielen
Deze gegevens kun je ophalen (GET):
- een lijst met profielen
- de profielen waar een gebruiker aan gekoppeld is
Deze opdrachten kun je geven (POST):
- gebruikers aan een profiel koppelen
- gebruikers van een profiel ontkoppelen