Intro Releasenotes Documentatie & testen ClientID Access Token Webhooks Postman Best practices Unauthorized(401) Forbidden(403) Limiet Bereikt (429) Meldingen FAQ Terminologie Use case: bijwerken persoon Use case: niet beschikbaarheid Use case: aanbod op website Use case: inschrijving versturen  Datamodel


Via Swagger vind je een documentatiepagina voor zowel de live- als trainingsomgeving van Coachview. Op deze documentatiepagina vind je de API (entiteiten) en mogelijke instructies (requests) die op dit moment beschikbaar zijn. 

Documentatie pagina's:
Het is belangrijk om te weten dat er twee documentatie pagina's zijn, omdat er een verschil kan zijn in data en de beschikbare endpoints voor de live- en trainingsomgeving van Coachview.
Op deze documentatie pagina's vind je een lijst met de verschillende endpoints waarvoor een of meerdere requests beschikbaar zijn. De requests zijn gebundeld per entiteit.
  1. Klik hier voor de documentatie pagina van de trainingsomgeving van Coachview.
  2. Klik hier voor de documentatie pagina van de live-omgeving van Coachview.


Let op: 
  1. Het is niet mogelijk om in de live-omgeving met Swagger te testen! 
  2. De Swagger pagina van de trainingsomgeving kan anders zijn dan de Swagger pagina van de live omgeving, omdat nieuwe toevoegingen eerst op training beschikbaar komen.


Inloggen:
Wil je alleen de documentatie inzien dan is inloggen niet nodig. Wil je testen, dan is een inlog noodzakelijk. Je maakt dan gebruik van een access token. Daarmee krijg je toegang tot de API bibliotheek.
Om de documentatie pagina te openen klik je bijvoorbeeld op deze link, die verwijst naar de trainingsomgeving van Coachview.
Klik op de knop 'Authorize', hiermee krijg je toegang tot de API en kun je gaan testen.
Het volgende scherm wordt geopend.
  1. Er wordt automatisch een client-id gegenereerd.
  2. Vink 'api algemene toegang tot de api' altijd aan.
  3. Lijst met scopes (endpoints). Vink de endpoints aan die je wilt gebruiken voor de test. Ben je aan het testen en heb je hier vergeten de te testen API aan te vinken? Dan krijg je niet de juiste waardes terug maar voorbeelden. Alle publicid's zijn dan hetzelfde.
Scrol vervolgens naar beneden en klik op de knop 'Authorize'.
Ben je nog niet ingelogd in Coachview? Dan verschijnt het Coachview inlogscherm. Log in met een gebruikersaccount met voldoende lees- en schrijfrechten.
Ben je ingelogd dan wordt je automatisch teruggestuurd naar de documentatie pagina van Swagger.
  1. Je ziet hier dat je bent geautoriseerd.
  2. Sluit het scherm.
  3. Sluit het scherm en logout.
Vergeet niet als je klaar bent om uit te loggen!

Lijst met endpoints:
Je komt terug op de documentatie pagina. Is het slotje gesloten dan ben je nog steeds geautoriseerd.
De pagina geeft verder een overzicht van endpoints waarvoor één of meerdere requests beschikbaar zijn.


Requests.
Klik je op de naam van een API (entiteit), dan zie je de requests die binnen deze API mogelijk zijn.
  1. Get: ophalen van data.
  2. Post: toevoegen van data.
  3. Put: wijzigen van data.
  4. Delete: verwijderen van data.
  5. Patch: wijzigen van een deel van de data.
  1. Een gesloten slotje geeft aan dat je bent geautoriseerd en kunt testen.
  2. Een open slotje geeft aan dat je niet bent geautoriseerd en dat je alleen de informatie kunt bekijken.
Klik je op de naam van een request, dan krijg je de documentatie te zien. Als voorbeeld de GET voor het ophalen van opleidingen.
Je ziet als eerste een korte uitleg en enkele voorbeelden.
Daaronder vind je de verschillende parameters, met per parameter een korte uitleg en enkele voorbeelden.
Daaronder vind je verschillende zoekmogelijkheden, Search.
Met een korte uitleg van de zoekmogelijkheden, voorbeelden wat je kunt invullen.
  1. Voorbeeld wat je kunt invullen.
  2. Vul zelf je zoekcriterium in. ?Search= mag je hierbij weglaten. Bijvoorbeeld de code of de naam of een gedeelte daarvan van de opleiding.
Klik allereerst op de knop 'Try it out'.
Vul bij de verschillende parameters of het zoekveld een waarde in.
Scroll helemaal naar beneden totdat je de knop 'Execute' tegenkomt. Klik op deze knop om te testen.

Filters: 
Afhankelijke van de GET heb je de mogelijkheid om een of meerdere filters in te stellen.
Voorbeeld filter 1 tekst:
Tekst als filter. In dit voorbeeld kun je een of meerdere plaatsen toevoegen, gescheiden door een komma.

?Plaats= mag je weglaten.
Voorbeeld filter 2 InclusiefVrijeVelden:
Het is in Coachview voor verschillende dossiers, in dit geval de opleiding, een of meerdere vrije velden in te richten. Daarin wordt extra informatie vastgelegd die niet door Coachview beschikbaar is gesteld.
  1. -- niet van toepassing.
  2. true, ja geef me informatie uit de vrije velden.
  3. false, nee wil ik niet ophalen.
Voorbeeld filter 3 PublicID:
Een PublicID die verwijst naar een dossier in Coachview. In dit voorbeeld een docent. Je kunt meerdere id's combineren, gescheiden met een ',' (komma). ID's van, in dit geval, de docenten haal je met een andere API op.

Take:
Het aantal resultaten dat opgehaald moet worden. Standaard is het aantal tijdens kantooruren 10 en het maximum is 100. Groter dan 100 tijdens kantooruren geeft een foutmelding.

?take= mag je weglaten.

Skip:
Het aantal resultaten dat overgeslagen moet worden. Kun je gebruiken voor paginering van de opgehaalde data, in combinatie met take.

Order by:
Sorteermogelijkheden af (desc)- of oplopend (asc). Je kunt alle velden op het hoogste niveau gebruiken. Voor de opleiding bijvoorbeeld op naam en/of code. Het is ook mogelijk om meerdere velden te combineren door deze te scheiden met een ',' (komma). Standaard wordt oplopend gesorteerd.

Where:
Extra filters op één of meerdere velden op het hoogste niveau. Het is mogelijk om meerdere filters te combineren door de velden te scheiden met een ',' (komma).
Voorbeeld where 2 datumvelden en getallen:
Deze operators zijn toegestaan:
  1. Groter dan: >
  2. Kleiner dan: <
  3. Gelijk aan: =
  4. Niet gelijk aan: <>
  5. Groter dan of gelijk aan: >=
  6. Kleiner dan of gelijk aan: <=

Er kan een bereik opgegeven worden door twee data met een komma te scheiden.
Voorbeeld where 3 statusvelden:
Op meerdere waarden tegelijk filteren is mogelijk door de waarden met een ',' (komma) te scheiden.
Voorbeeld where 4 Ja/Nee velden:
Gebruik true (Ja) of false (Nee).
Voorbeeld where 5 vrije velden:
Als zoekcriterium moet je de code van het vrije veld meegeven, gevolgd door de te zoeken waarde. Alleen = (gelijk aan) en <> (ongelijk aan) zijn toegestaan.

In Coachview vind je de code voor het vrije veld 'VrijveldURLWebsite'  terug.

Count:
Alleen het aantal resultaten teruggeven, er wordt geen data opgehaald.

Wil je testen en dus waardes invullen? Klik dan op de knop 'Try it out'.
Na de parameters vind je de knop 'Execute'. Daarmee voer je de requests uit. Met de knop 'Clear', verschijnt na de eerste execute, verwijder je de ingevulde waardes.
Ben je klaar? Scroll naar boven en klik op de 'Cancel' knop.


Server response.
Het resultaat wordt teruggegeven met codes en indien succesvol met de opgehaalde data. Op https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses vind je meer informatie over "HTTP response status codes".
Code 200 -> Details:
Succesvol. Inclusief opgehaalde data.
Code 200 -> Description: 
Voorbeeld (geen echte) data.
Code 401 of 403:
Foutmeldingen.
Curl:
Informatie die nodig is om een request te doen bijvoorbeeld vanuit Postman.
Klik op dit icoontje om het resultaat te kopiëren. 
Request URL:
Je ziet hier hoe de request is uitgevoerd.
Achter /opleidingen zie je een ? om aan te geven dat er parameters volgen. In dit voorbeeld 'Take=1' vervolgt met een '&' om aan te geven dat er nog een parameter volgt.


Bijgewerkt tot en met versie 85