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

Inhoudsopgave:


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 API's voor de live- en trainingsomgeving van Coachview.
Op deze documentatie pagina's vind je een lijst met de verschillende API's 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: op dit moment kun je in de live-omgeving met Swagger niet testen.

Inloggen:
Wil je alleen de documentatie inzien dan is inloggen niet nodig. Wil je testen dan is een inlog noodzakelijk, de token is 30 minuten geldig.
Klik op de knop 'Authorize', hiermee geef je toegang tot de API's en kun je gaan testen.
Volgend scherm wordt geopend.
  1. Er wordt automatisch een client_id gegenereerd.
  2. Vink 'api algemene toegang tot de api's' altijd aan.
  3. Lijst met scopes (API's). Vink die API's 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.
Je wordt automatisch teruggestuurd naar de documentatie pagina van Swagger.

  1. Je ziet hier dat je bent geautoriseerd.
  2. Sluit het scherm.
  3. Sluit het scherm.
  4. Sluit het scherm en logout.
Vergeet niet als je klaar bent om uit te loggen.

Lijst met API's:
Je komt terug op de documentatie pagina. Is het slotje gesloten dan ben je nog steeds geautoriseerd.
De pagina geeft verder een overzicht van API's 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.
Search:
  1. Uitleg zoekmogelijkheden.
  2. Voorbeeld wat je kunt invullen.
  3. Vul zelf je zoekcriterium in. ?Search= mag je hierbij weglaten. Bijvoorbeeld de code of de naam of een gedeelte daarvan van de opleiding.

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 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 10 en het maximum is 100. Groter dan 100 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 1 tekstveld:
Zoeken op (een deel van) het veld.

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 hebben we als voorbeeld het vrije veld bij een opleiding.

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.

Server response:
Het resultaat wordt teruggegeven met codes en indien succesvol met de opgehaalde data.
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.