REST-API

Roy Fielding definieerde REST in 2000 in zijn proefschrift Architectural Styles and the Design of Network-based Software Architectures aan de University of California, Irvine. Hij werkte als redacteur aan de HTTP/1.1-specificaties en ontwikkelde REST parallel aan die standaard. De architectuurstijl is geen protocol, maar een verzameling principes voor communicatie tussen systemen over een netwerk.

2. Gebruik HTTP-methoden als bouwstenen

REST maakt gebruik van bestaande HTTP-methoden: `GET` haalt gegevens op, `POST` maakt een nieuwe bron aan, `PUT` wijzigt een bestaande bron, en `DELETE` verwijdert een bron. Deze methoden zijn gedefinieerd in RFC 7231, gepubliceerd door de IETF in juni 2014. De methoden zijn ofwel veilig (ze wijzigen niets, zoals `GET`) of idempotent (herhaalde uitvoering geeft hetzelfde resultaat, zoals `PUT` en `DELETE`).

3. Hanteer stateless communicatie

Elke aanvraag van een client naar een server bevat alle informatie die nodig is om die aanvraag te verwerken. De server onthoudt geen status tussen aanvragen door. Dit vereenvoudigt de serverkant omdat er geen sessiestatus moet worden bijgehouden, en maakt horizontaal schalen eenvoudig: elke aanvraag kan naar elke beschikbare server worden doorgestuurd zonder context over te dragen.

4. Identificeer bronnen met URI's

Elke bron — een gebruiker, product of bestelling — heeft een unieke URI. De client communiceert met deze bron via HTTP-methoden. Een `GET`-aanvraag haalt gegevens op, een `POST` maakt een nieuwe bron aan. Deze consistente aanpak maakt REST eenvoudig te implementeren en draagt bij aan de uniformiteit van web-API's.

5. Werk met JSON en verwerk het met jq

RESTful API's gebruiken meestal JSON als gegevensformaat. JSON is lichtgewicht en werkt goed met JavaScript. Gebruik `jq` om JSON-antwoorden te filteren en te aggregeren. Bijvoorbeeld, om de som van prijzen uit een productlijst te berekenen:

curl -s https://api.example.com/products | jq 'map(.price) | add'

Dit commando haalt de productlijst op, pakt alle prijzen en telt ze op.

6. Bouw een REST API met Node.js

Node.js is een server-side JavaScript runtime die asynchroon werkt en veel gelijktijdige aanvragen efficiënt verwerkt. Dit sluit goed aan bij de stateless aard van REST. Een eenvoudige API luistert op HTTP, exposeert bronnen via URL's en geeft JSON-antwoorden terug. Gebruik Express 4.18 of hoger voor routing:

npm init -y
   npm install express

Maak een bestand `server.js`:

const express = require('express');
   const app = express();
   app.use(express.json());</p><p>const products = [{ id: 1, name: 'Laptop', price: 999 }];</p><p>app.get('/products', (req, res) => {
     res.json(products);
   });</p><p>app.post('/products', (req, res) => {
     const product = { id: products.length + 1, ...req.body };
     products.push(product);
     res.status(201).json(product);
   });</p><p>app.listen(3000, () => console.log('API listening on port 3000'));

Start de server met `node server.js`.

7. Raadpleeg een bestaande REST API

De BelgicaPress API biedt toegang tot gedigitaliseerde Belgische kranten uit 1800–1970. Via HTTP-aanvragen kunt u artikelen opvragen op trefwoord, datum, krantentitel of regio. De API ondersteunt ook IIIF (International Image Interoperability Framework) voor hoge-resolutie beeldmateriaal. Dit toont aan dat REST niet alleen tekstuele gegevens levert, maar ook mediabestanden zoals scans van historische kranten.

Europeana Newspapers biedt eveneens een REST API aan voor cultureel erfgoed. Gebruikers krijgen via een gratis API-key toegang tot krantenartikelen uit verschillende landen, waaronder België. Authenticatie via een API-sleutel is een veelgebruikte methode bij REST API's om toegang te beheren zonder volledige gebruikersaccounts.

8. Herken de beperkingen van REST

Veel zogenaamde REST API's voldoen niet aan alle principes van REST, met name de vereiste om hypermedia te gebruiken (HATEOAS, Hypermedia as the Engine of Application State). Een strikt RESTful systeem geeft naast gegevens ook links terug die aangeven welke acties mogelijk zijn, zodat de client de API dynamisch kan navigeren. API's die dit niet doen worden soms "REST-like" of "HTTP API's" genoemd. Toch blijft de term REST algemeen gebruikt voor API's die HTTP-methoden en statuscodes gestructureerd toepassen.

Verificatie

curl http://localhost:3000/products

Dit geeft de lijst met producten terug in JSON-formaat. Maak een nieuw product aan:

curl -X POST http://localhost:3000/products \
  -H "Content-Type: application/json" \
  -d '{"name":"Monitor","price":299}'

Controleer daarna of het product in de lijst staat:

curl http://localhost:3000/products | jq '.[] | select(.name=="Monitor")'

Veelgestelde problemen

Voeg CORS-headers toe aan uw Express-server:

npm install cors

const cors = require('cors');
   app.use(cors());

2. JSON parse error bij het versturen van een POST-aanvraag

Zorg dat de Content-Type header correct is ingesteld op `application/json` en dat de body geldige JSON bevat. Controleer met `jq` of de JSON geldig is:

echo '{"name":"Test"}' | jq .

3. API geeft 404 terug bij een geldige URI

Controleer of de route exact overeenkomt met de URI in uw Express-app. Express routes zijn hoofdlettergevoelig en matchen op het volledige pad. Gebruik `app.get('/products/:id')` voor dynamische routes. ```