# Server-side API
Een Server-side API wordt gebruikt om communicatie tussen de server (waar gegevens of functionaliteit worden opgeslagen) en clienttoepassingen mogelijk te maken.
Via HTTP-requests, meestal met behulp van methoden zoals GET, POST, PUT, PATCH, en DELETE, kan een client applicatie gegevens opvragen, verzenden, bijwerken of verwijderen van de server.
Om zelf een API samen te stellen, is het essentieel dat we eerst goed kunnen werken met URL’s en alle onderdelen hier van begrijpen.
# URI en URL
Een Uniform Resource Locator (Afk. URL), anders gekend als een webadres, is een referentie naar een online resource dat de locatie van een bron aangeeft en de middelen beschrijft waarmee deze bron kan worden opgehaald. Een URL is een specifiek type van Uniform Resource Identifier (Afk. URI).
Een URI is een verzameling van karakters dat een specifieke resource identificeert op het internet op een uniforme manier. URI’s volgen een voorgedefinieerde verzameling van syntax regels en is uitbreidbaar.
Een URL string is een gestructureerde string dat verschillende componenten bevat. Dit resulteert in een object bestaande uit eigenschappen. De url module implementeert de WHATWG URL standard (opens new window).
Alle URL’s zijn URI’s, maar niet alle URI’s zijn URL’s. Een URI kan namelijk ook gewoon een identificatie zijn zonder dat het aangeeft hoe je de bron kunt ophalen of waar deze zich precies bevindt.
Om een URL object (opens new window) aan te maken op basis van een url-string implementeren we de volgende code:
let myURL = new URL(
"https://user:[email protected]:8080/p/a/t/h?query=string#hash"
);
console.log(myURL);
2
3
4
Resultaat in de commandline:
URL {
href: 'https://user:[email protected]:8080/p/a/t/h?query=string#hash',
origin: 'https://sub.example.com:8080',
protocol: 'https:',
username: 'user',
password: 'pass',
host: 'sub.example.com:8080',
hostname: 'sub.example.com',
port: '8080',
pathname: '/p/a/t/h',
search: '?query=string',
searchParams: URLSearchParams { 'query' => 'string' },
hash: '#hash'
}
2
3
4
5
6
7
8
9
10
11
12
13
14
De eigenschappen kunnen bevraagd worden via het object:
console.log(myURL.hostname); // sub.example.com
console.log(myURL.hash); // #hash
2
Nieuwe waarden kunnen ook aan deze eigenschappen toegekend worden:
myURL = new URL("http://www.pgm.gent/students?class=1pgm#a");
console.log(myURL.pathname); // #hash
myURL.pathname = "lecturers";
myURL.protocol = "https";
console.log(myURL);
2
3
4
5
Resultaat in de commandline:
URL {
href: 'https://www.pgm.gent/lecturers?class=1pgm#a',
origin: 'https://www.pgm.gent',
protocol: 'https:',
username: '',
password: '',
host: 'www.pgm.gent',
hostname: 'www.pgm.gent',
port: '',
pathname: '/lecturers',
search: '?class=1pgm',
searchParams: URLSearchParams { 'class' => '1pgm' },
hash: '#a'
}
2
3
4
5
6
7
8
9
10
11
12
13
14
Met de URLSearchParams API hebben we lees- en schrijfrechten tot de query van een URL. Met de URLSearchParams klasse kunnen we zelfs search parameters aanmaken from scratch. Via de eigenschap searchParams van het url-object kunnen we zoekparameters op vragen. In he volgende voorbeeld zoeken we naar pastinaak via de Google zoekmachine dat resulteert in de volgende url in de code:
myURL = new URL(
"https://www.google.be/search?source=hp&ei=iCqwX_ruOM29lwSSsp6IDw&q=pastinaak&oq=pastinaak&gs_lcp=CgZwc3ktYWIQAzIICC4QsQMQkwIyCAgAELEDEIMBMggIABCxAxCDATICCAAyAggAMgIIADICCAAyAggAMgIIADICCAA6BQgAELEDOgUILhCxAzoICC4QsQMQgwE6AgguUM8UWJAiYKMkaABwAHgAgAFViAGoBZIBATmYAQCgAQGqAQdnd3Mtd2l6&sclient=psy-ab&ved=0ahUKEwj60p-o3YLtAhXN3oUKHRKZB_EQ4dUDCAs&uact=5"
);
console.log(myURL.searchParams);
2
3
4
Resultaat in de commandline van de searchParams eigenschap:
URLSearchParams {
'source' => 'hp',
'ei' => 'iCqwX_ruOM29lwSSsp6IDw',
'q' => 'pastinaak',
'oq' => 'pastinaak',
'gs_lcp' => 'CgZwc3ktYWIQAzIICC4QsQMQkwIyCAgAELEDEIMBMggIABCxAxCDATICCAAyAggAMgIIADICCAAyAggAMgIIADICCAA6BQgAELEDOgUIL
hCxAzoICC4QsQMQgwE6AgguUM8UWJAiYKMkaABwAHgAgAFViAGoBZIBATmYAQCgAQGqAQdnd3Mtd2l6',
'sclient' => 'psy-ab',
'ved' => '0ahUKEwj60p-o3YLtAhXN3oUKHRKZB_EQ4dUDCAs',
'uact' => '5' }
2
3
4
5
6
7
8
9
10
In de key of eigenschap q in het URLSearchParams object zit de zoekroutine die we via het invulveld in de zoekmachine hebben ingegeven. In dit geval hebben we gezocht naar pastinaak. Om deze key op te vragen kunnen we de volgende code toepassen:
const q = myURL.searchParams.get("q");
console.log(q); // pastinaak
2
We kunnen ook een nieuw URLSearchParams object aanmaken om vervolgens search parameters hierin dynamisch toe te voegen:
let searchParams = new URLSearchParams();
searchParams.append("sort", "price");
searchParams.append("rating", "all");
console.log(searchParams.toString()); // sort=price&rating=all
2
3
4
De waarde van een bestaande zoekparameter kan aangepast worden via de set methode:
searchParams.set("sort", "rank");
searchParams.set("rating", "4");
console.log(searchParams.toString()); // sort=rank&rating=4
2
3
Voorbeeld: conctructie van een URL m.b.v. URL en de URLSearchParams klasse:
const finalURL = new URL("https://example.org/");
finalURL.protocol = "https";
finalURL.hostname = "www.bol.com";
finalURL.pathname = "products";
finalURL.search = new URLSearchParams("sort=price&rating=all");
console.log(finalURL.toString()); // https://www.bol.com/products?sort=price&rating=all
2
3
4
5
6
# REST
REST staat voor “Representational State Transfer”. Het is een architecturale stijl voor softwareapplicaties in een netwerk. Het is bij uitstek de voornaamste architecturale stijl voor online services, omwille van de minder grote- en minder complexe aanvragen (requests).
Op het web zijn er vele entiteiten (resources). Een resource wordt beschikbaar gesteld via een URL, bijv.: http://www.arteveldehs.be/opleidingen/gdm. Het bezoeken van zo’n URL geeft de representatie van zo’n resource terug, waardoor de cliënt in een bepaalde status (state) verkeerd. Klikt de gebruiker op een aanwezige link binnen de voorgaande representatie, dan krijgt deze cliënt een nieuwe representatie en verkeerd dus hierdoor in een nieuwe status!
REST biedt een uniforme interface met standaard HTTP-methoden zoals GET, POST, PUT en DELETE voor het manipuleren van resources.
De architecturale elementen binnen een REST service:
- Resource Elke data die je kan benoemen, vergelijkbaar met een entiteit of een verzameling van entiteiten
- Resource Identifier Meestal URI (Uniform Resource Identifier): URL (Uniform Resource Locator) + URN (Uniform Resource Name)
- Resource Metadata Link naar de bron, alternatieven en varianten
- Representation Een document (XML, (X)HTML, JSON§ …)
- Representation Metadata Mediatype (text/xml, text/html …)
Een cliënt doet een aanvraag naar een resource via de resource identifier of URI. De controller, die verbonden is aan deze URI, verwerkt de aanvraag en haalt via de Service laag de noodzakelijke data op. Deze data wordt vervolgens in de controller geconverteerd of getransformeerd naar het aangevraagde formaat. Tenslotte wordt deze data verstuurd naar de cliënt die deze data zal verwerken via scripts.
# RESTful
REST is een abstracte architecturale stijl die toepasbaar is in vele technologieën. Als men de principes van REST toepast in combinatie met HTTP (HyperText Transfer Protocol), dan spreekt men over RESTful HTTP of kortweg RESTful.
De RESTful URL’s identificeren de dingen waarop we willen inwerken. Een URL identificeert een resource:
/studentsIdentificatie van alle studenten/students/phildpIdentificeert een student, genaamd phildp In dit geval moet de identificatie uniek zijn, vandaar dat we hier de gebruikersnaam gebruikenDe resource identifiermoet uniek zijn
Aanvraag (request) van een resource naar een host
GET /students/phildp HTTP/1.1, Host:arteveldehs.be
# RESTful naamgeving
In RESTful beschrijven we het “resource path” met zelfstandige naamwoorden (Eng. nouns) en dus niet via het omschrijven van acties: /students/add. Dit is dus een ongeldig resource path in RESTful applicaties. De URLs moeten zo precies mogelijk omschreven worden, alles wat de resource uniek maakt zou in de URL aanwezig moeten zijn, zoals bijv.: primaire sleutels, gebruikersnamen …
Bij iedere aanvraag of “request” specificeren we een bepaalde HTTP verb of methode in de “request header”. Deze HTTP method is het eerste woord, in hoofdletters, in de “request header”. De HTTP methoden vertellen de server wat deze moet doen met de data geïdentificeerd door de URL. De “request” kan daarnaast ook data bevatten die mee verstuurd zal worden. Deze data brengen we onder in de “request body”.
| Databasebewerkingen | SQL keyword | HTTP methods | Status code | Omschrijving |
|---|---|---|---|---|
| Create | INSERT | POST | 201 | Aanmaak van een resource |
| Read | SELECT | GET | 200 | Lezen van de representatie van een resource |
| Update | UPDATE | PUT | 204 | Wijzigen van een resource |
| Update | UPDATE | PATCH | 204 | Kleine wijziging van een resource |
| Delete | DROP | DELETE | 204 | Verwijderen van een resource |
De GET methode is de meest eenvoudige HTTP request methode. De browser gebruikt deze iedere keer wanneer een gebruiker klikt op een link of een URL typt in de adresbalk. Het geeft instructies aan de server om de representatie van de resource door te sturen naar de cliënt. Wordt voornamelijk gebruikt in Read-only of safe methods.
| HTTP methods | Omschrijving |
|---|---|
| CONNECT | SSL connecties en proxy chaining |
| HEAD | Vergelijkbaar met GET, maar de representatie wordt niet teruggegeven enkel de HTTP header. Handig om bijvoorbeeld eerst na te gaan of een resource gewijzigd is, vooraleer we deze resource zullen downloaden via GET! |
| TRACE | Wordt gebruikt om bepaalde elementen te traceren tijdens de debug-fase. Meestal worden deze TRACE request uitgeschakeld door bepaalde condities te overschrijven! |
# RESTful richtlijnen
# Meervoudige zelfstandige naamwoorden
Gebruik meervoudsvormen voor resource-namen om de consistentie te behouden. Gebruik ook zelfstandige naamwoorden en geen werkwoorden.
# Duidelijke en begrijpelijke namen:
Kies namen die intuïtief en begrijpelijk zijn voor ontwikkelaars. Vermijd afkortingen en gebruik volledige woorden.
# Hiërarchie
Als er hiërarchieën bestaan tussen resources, laat dit dan weerspiegelen in de URI. Zorg ervoor dat resource-namen meervoudsvormen zijn om een duidelijk onderscheid te maken tussen individuele items en collecties.
# Gebruik HTTP-methoden
Gebruik de juiste HTTP-methoden zoals GET, POST, PUT, en DELETE op een consistente manier. Bijvoorbeeld, gebruik GET voor het ophalen van gegevens, POST voor het maken van een nieuwe resource, PUT voor het bijwerken van een bestaande resource, en DELETE voor het verwijderen ervan.
# Gebruik werkwoorden voor specifieke acties
Gebruik werkwoorden om specifieke acties op resources aan te geven. Bijvoorbeeld, gebruik /activate voor het activeren van een account. Let op dat je hier geen CRUD-acties definieert (/create, /read, /update, /delete).
# Filter met query’s op collecties
Maak het mogelijk om collecties te filteren, sorteren en beperken met queryparameters.
# API Web Client
Een API-client is een ontwikkelingstool waarmee we API’s gemakkelijk kunnen ontdekken, testen en debuggen.Het biedt een grafische gebruikersinterface waarmee ontwikkelaars gemakkelijk kunnen communiceren met API’s zonder handmatig HTTP-verzoeken te schrijven of terminalcommando’s uit te voeren.
API-clients nemen een deel van de complexiteit rond API-development weg, je hoeft namelijk zelf geen taal of framework te kennen. Hierdoor wordt de toegangsdrempel voor API-gerelateerd werk verlaagd en kunnen ontwikkelaars zich meer concentreren op andere zaken.
# API-first development
‘API-first’ development is een benadering van softwareontwikkeling waarbij de nadruk ligt op het ontwerpen en ontwikkelen van de API voordat andere delen van de applicatie worden gebouwd. Het idee achter ‘API-first’ development is om de API te beschouwen als een fundamenteel element tussen verschillende onderdelen van een applicatie, zoals de front-end en de back-end.
API clients kunnen een belangrijke rol spelen bij ‘API-first’ development door de efficiëntie van het ontwikkelingsproces te vergroten en de samenwerking tussen teams te verbeteren.
# Waarom een visuele API client gebruiken?
API-clients stellen ontwikkelaars in staat om gegevens op te halen of uit te wisselen met externe servers zonder te coderen. Ze kunnen via een visuele interface verzoeken naar de API sturen om gegevens op te halen, bij te werken, te verwijderen of te creëren.Ontwikkelaars kunnen de structuur van de gegevens bekijken, wat handig is bij het begrijpen van de API-output en zal een essentiële tool zijn voor iedere back- en front-end developer.
# Snel prototypes ontwikkelen
API clients stellen ontwikkelaars in staat om snel prototypes van API-verzoeken te maken en te testen. Dit versnelt het ontwerpproces en maakt het mogelijk om vroeg feedback te verzamelen.
# Snel testen en debuggen
Ontwikkelaars kunnen API-verzoeken snel testen en fouten opsporen met behulp van API clients. Dit draagt bij aan een vlotte ontwikkelingscyclus en snelle probleemoplossing.
# HTTP-serverfouten
HTTP-serverfouten, ook wel bekend als 5xx-statuscodes, geven aan dat er een probleem is aan de zijde van de server bij het verwerken van een verzoek. Wanneer je gebruik maakt van een API client kan je met zekerheid weten dat de fout niet aan jouw code ligt.
# 500 Internal Server Error:
Dit is een algemene foutmelding die aangeeft dat er iets mis is gegaan aan de zijde van de server, maar de server kan niet specifiek aangeven wat het probleem is.
# 502 Bad Gateway:
Geeft aan dat de server, terwijl hij als gateway of proxy fungeert, een ongeldige reactie heeft ontvangen van de upstream-server.
# 503 Service Unavailable:
Geeft aan dat de server tijdelijk niet in staat is om het verzoek te verwerken. Dit kan zijn vanwege overbelasting of onderhoud.
# 504 Gateway Timeout:
Geeft aan dat de server, terwijl hij als gateway of proxy fungeert, geen tijdige reactie heeft ontvangen van de upstream-server of andere bron.
# 507 Insufficient Storage:
Geeft aan dat de server niet in staat is om het verzoek te verwerken omdat er onvoldoende opslagruimte is.
# 508 Loop Detected:
Geeft aan dat de server een oneindige lus heeft gedetecteerd tijdens het verwerken van het verzoek.
# Samenwerking tussen Front-end en Back-end
API clients fungeren als een gemeenschappelijk platform waar zowel front-end als back-end ontwikkelaars kunnen samenwerken. Ze kunnen dezelfde API-specificaties gebruiken om ervoor te zorgen dat beide componenten correct met elkaar communiceren.
Een API-client API is een vorm van interactieve API-documentatie. Deze tool maakt het structureren en begrijpen van API-endpoints en parameters eenvoudiger.