Waarom goede API's cruciaal zijn
Een API (Application Programming Interface) is het zenuwstelsel van moderne software. Je mobiele app praat ermee, je frontend haalt er data uit, en externe partners koppelen erop aan. Een slecht ontworpen API kost je maanden aan refactoring. Een goed ontworpen API schaalt moeiteloos mee met je groei. Bij NedDev bouwen we dagelijks API's — hier delen we onze best practices.
REST vs GraphQL: wanneer wat?
REST
REST is de standaard voor de meeste API's en dat is niet zonder reden. Het is eenvoudig, breed ondersteund en makkelijk te cachen.
Kies REST wanneer:
Je API voornamelijk CRUD-operaties uitvoertCaching belangrijk is (HTTP caching werkt out-of-the-box)Je een breed publiek bedient (iedereen kent REST)Je microservices bouwt
Best practices voor REST:
Gebruik zelfstandige naamwoorden voor endpoints: `/users`, niet `/getUsers`HTTP methods correct toepassen: GET, POST, PUT, PATCH, DELETEConsistente response structuur met envelop: `{ data: ..., meta: ..., errors: ... }`HTTP statuscodes correct gebruiken (200, 201, 400, 401, 403, 404, 500)Paginering via cursor-based pagination (niet offset-based voor grote datasets)
GraphQL
GraphQL lost het over-fetching en under-fetching probleem op. De client vraagt precies de data die het nodig heeft.
Kies GraphQL wanneer:
Je frontend complexe, geneste data nodig heeftMeerdere clients (web, mobiel, IoT) verschillende data requirements hebbenJe over-fetching wilt voorkomen op mobiele verbindingenJe een data-intensieve applicatie bouwt
Let op:
GraphQL vereist meer setup en toolingCaching is complexer (geen HTTP caching)N+1 query probleem vereist DataLoader of vergelijkbare oplossingen
Authenticatie en autorisatie
API Keys
Simpelste optie. Geschikt voor server-to-server communicatie. Niet voor frontend gebruik — API keys zijn zichtbaar in de browser.
JWT (JSON Web Tokens)
De standaard voor gebruikersauthenticatie. Stateless, schaalbaar en breed ondersteund.
Best practices:
Korte expiry tijd (15 minuten) met refresh tokensSla JWTs op in httpOnly cookies, niet in localStorageGebruik RS256 (asymmetrisch) in plaats van HS256 voor multi-service architecturenValideer altijd de issuer, audience en expiry
OAuth 2.0
Gebruik OAuth wanneer je third-party integraties aanbiedt. Implementeer PKCE voor publieke clients (mobiele apps, SPAs).
Versioning
Je API zal veranderen. Plan hier vanaf dag één voor:
URL versioning (`/api/v1/users`): Meest voorkomend, duidelijk en eenvoudigHeader versioning (`Accept: application/vnd.api+json;version=2`): Schoner maar complexerGeen breaking changes: De beste versioning is geen versioning. Voeg toe, verwijder niet
Rate limiting en throttling
Bescherm je API tegen misbruik en overbelasting:
Implementeer rate limiting per API key of gebruikerGebruik sliding window algoritme (niet fixed window)Retourneer duidelijke headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`Return HTTP 429 (Too Many Requests) bij overschrijdingOverweeg gedifferentieerde limieten per plan (gratis vs betaald)
Documentatie
Een API zonder documentatie is een API die niemand gebruikt.
OpenAPI/Swagger: De standaard voor REST API documentatie. Genereer interactieve docs automatischVoorbeelden bij elk endpoint: Developers lezen voorbeelden, niet specificatiesChangelog bijhouden: Communiceer wijzigingen proactiefPostman/Insomnia collections: Deel kant-en-klare request collections
Error handling
Goede error responses besparen je support team uren:
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Het e-mailadres is ongeldig",
"details": [
{ "field": "email", "message": "Voer een geldig e-mailadres in" }
]
}
}
```
Gebruik machine-readable error codes naast menselijke berichten. Log errors server-side met context (request ID, user ID, timestamp).
Monitoring en observability
Implementeer request tracing met een uniek request IDMonitor latency per endpoint (P50, P95, P99)Alert op error rate spikes (>1% 5xx responses)Gebruik tools als Grafana, Datadog of Vercel Analytics
Ons advies
Start met REST tenzij je een concrete reden hebt voor GraphQL. Investeer vanaf dag één in authenticatie, rate limiting en documentatie. En test je API met geautomatiseerde integration tests — handmatig testen schaalt niet.