Getting started

In deze sectie doorlopen we de stappen om een eigen API op te zetten en leer je hoe je zowel de API als de interactieve documentatie gebruikt met behulp van een voorbeeldproject.

1. Maak een project ID aan

Op de homepagina kun je je registreren je met je NOVI student-e-mailadres. Na registratie ontvang je per e-mail een unieke Project ID. Deze heb je nodig om toegang te krijgen tot jouw eigen, persoonlijke omgeving. Bewaar deze goed.

2. Maak een database-configuratie-bestand

Maak een bestand aan op jouw computer met een .json-extensie. Open dit bestand vervolgens met WebStorm en plak jouw database-configuratie erin. Als dit de eerste keer is dat je deze API gebruikt, kun je om te beginnen deze JSON-voorbeeld-configuratie voor een online bibliotheek gebruiken. Deze vervang je later door je eigen databaseontwerp.

3. Upload je gegevens

Op de homepagina kun je jouw Project ID invullen en het JSON-configuratiebestand uploaden. Zodra je dit hebt gedaan, wordt je API direct gegenereerd en krijg je toegang tot de interactieve documentatie via Swagger UI via de ' Bekijk Swagger UI'-knop klikken.

Hoe gebruik ik de API?

Wanneer de interactieve documentatie gegenereerd is, is de API klaar voor gebruik op de volgende base URL die verreikt kan worden met de beschikbare endpoints:

BASE URL

https://novi-backend-api-wgsgz.ondigitalocean.app/

Omdat meerdere studenten tegelijkertijd met hun eigen API-configuratie werken, is het nodig om jouw unieke Project ID mee te sturen. Hiermee weet het systeem precies welke database en instellingen bij jouw project horen. Je stuurt jouw ID bij ieder request mee onder de naam novi-education-project-id in de request-header:

{
  'novi-education-project-id': 'xxx-xxx-xxxx-xxx'
}

Wanneer je een verzoek wil doen naar een afgeschermd endpoint, zul je daarnaast ook een JWT-token mee moeten sturen onder de naam Authorization in de request-header:

{
  'Authorization': 'Bearer xxx.xxx.xxx'
}

Je verkrijgt een JWT-token door een bestaande gebruiker in te loggen via het POST /api/login endpoint. Of een endpoint openbaar of afgeschermd is, bepaal je zelf in jouw configuratie-bestand.

Hoe gebruik ik de Interactieve API documentatie?

De Swagger UI geeft je een visuele, klikbare weergave van de API. Hiermee kun je makkelijk ontdekken welke endpoints er zijn en ze direct uitproberen. Ideaal om mee te testen voordat je je frontend-app eraan koppelt.

Wanneer je een verzoek wil doen naar openbaar endpoint, is het meesturen van jouw project ID verplicht. Wanneer je het endpoint uitprobeert in Swagger, wordt deze ID automatisch voor je meegestuurd. In de database-opzet voor de online bibliotheek zijn de endpoints voor het opvragen van boeken, auteurs en genres openbaar (toegankelijk voor zowel ingelogde als niet-ingelogde gebruikers). Het opvragen van alle boeken kun je als volgt uitproberen in de Swagger-documentatie:

  1. Klik op het endpoint dat je wilt proberen, in ons geval GET api/books
  2. Klik op de knop "Try it out" (rechtsbovenaan)
  3. Klik vervolgens op de "Execute"-knop om het verzoek uit te voeren
  4. De response (zoals je die in jouw Frontend zult ontvangen) wordt zichtbaar:
    • Je ziet de volledige URL waar het request naartoe gemaakt is en de headers die Swagger voor je heeft meegestuurd ( curl);
    • Je ziet alle boeken (response body) die op dit moment in de database staan en door de API zijn teruggestuurd;
    • Je ziet de response-headers die de API heeft teruggestuurd (hierin vind je bijvoorbeeld de statuscode)

Beveiligde endpoints

Wanneer je een verzoek wil doen naar één van de afgeschermde endpoints, is het meesturen van jouw project ID én JWT token verplicht. Een token verkrijg je normaliter door je als gebruiker in te loggen bij de frontend applicatie. Wanneer je zo'n endpoint wil uitproberen in Swagger, zul je dus eerst een login-verzoek moeten sturen. Daarna krijg je toegang tot afgeschermde endpoints:

  1. Klik op het Authorization POST /api/login endpoint, helemaal onderaan
  2. Klik op de knop "Try it out"
  3. Je krijgt nu de mogelijkheid om de request body (de inloggegevens die worden verstuurd) aan te passen. In de bibliotheekdatabase is al een admin account aanwezig, dus je kunt de volgende waardes invullen:
{
  "email": "[email protected]",
  "password": "admin123"
}
  1. Klik vervolgens op de "Execute"-knop om het verzoek uit te voeren
  2. De response (alle user-gegevens) wordt zichtbaar. Kopieer de waarde die achter token uitgeschreven staat
  3. Scrol helemaal omhoog naar de bovenkant van de documentatie en druk op de "Authorize"-knop
  4. Plak de token (zonder "") in het invoerveld
  5. Klik op "Authorize" en sluit de pop-up. Je hebt Swagger nu als het ware "ingelogd".

Je kunt nu gebruikmaken van alle beveiligde endpoints, omdat Swagger de token nu automatisch voor je mee zal sturen als je andere requests uitprobeert.

Wat staat er in het configuratiebestand?

Hoewel je in de komende secties stap voor stap leert hoe je zelf een configuratiebestand opzet, kan het helpen om eerst een kijkje te nemen in het configuratiebestand van de online bibliotheek. Dit voorbeeld laat goed zien hoe je verschillende soorten collecties, relaties en toegangsrechten kunt instellen. Het bestand begint met collecties en hun velden:

  • Books – boeken die uitleenbaar zijn. Elk boek moet een titel, ISBN, prijs, beschikbaarheidsstatus, en verwijzingen naar een auteur en genre bevatten.
  • Authors – schrijvers van de boeken krijgen een naam en korte biografie. Deze zijn expres geen onderdeel van de boeken, omdat een auteur meerdere boeken kan schrijven en je die data niet telkens wil kopiëren.
  • Genres – categorieën waar boeken onder vallen, zoals Science Fiction of Non-Fictie.
  • Members – informatie over geregistreerde leden van de bibliotheek, zoals naam, e-mailadres en lidmaatschapsinformatie.
  • Loans – uitleenregistraties, die bijhouden welk lid welk boek heeft geleend, met data voor uitlening en terugbrengen.

Deze collecties zijn met elkaar verbonden via zogeheten references. Elk boek verwijst naar een auteur en genre, en elke uitleenregistratie naar een boek en lid. Ook zijn er al drie vooraf ingestelde gebruikers aanwezig:

Onderaan het bestand vind je de daadwerkelijke data: vier genres, drie boeken en auteurs, twee bibliotheekleden en één uitleenregistratie zijn alvast ingevuld. Deze startdata is meteen beschikbaar in je database en kan via de API-endpoints worden aangevuld, aangepast of verwijderd.

In de volgende secties lees je meer over alle onderdelen die komen kijken bij het opzetten van collecties, velden en het toevoegen van data.