Inhoudsopgave
Een API is een contract tussen systemen. Wie hem bouwt denkt vaak vanuit de implementatie, maar de gebruiker van die API — of dat nu een frontend developer, een externe partij of jezelf over zes maanden is — denkt vanuit verwachting en gemak. Een slecht ontworpen API dwingt zijn gebruikers tot workarounds, leidt tot verkeerd gebruik en is een constante bron van frustratie. Een goed ontworpen API voelt intuïtief, is consistent en heeft zo weinig mogelijk uitleg nodig om mee aan de slag te gaan.
Naamgeving en structuur van endpoints
Endpoints zijn de voordeur van je API en de naamgeving ervan bepaalt direct hoe begrijpelijk de interface is. Gebruik zelfstandige naamwoorden in plaats van werkwoorden — /users in plaats van /getUsers — en houd de hiërarchie logisch: /users/{id}/orders voor de bestellingen van een specifieke gebruiker. HTTP-methodes als GET, POST, PUT, PATCH en DELETE zijn de werkwoorden; de URL is de resource. Consistentie in meervoud versus enkelvoud, hoofdlettergebruik en scheidingstekens voorkomt verwarring en maakt de API voorspelbaar voor iedereen die hem gebruikt.
Statuscodes correct gebruiken
Een van de meest gemaakte fouten is het teruggeven van een 200 OK bij een fout, met de foutmelding verstopt in de response body. HTTP-statuscodes bestaan juist om de uitkomst van een request te communiceren zonder de body te hoeven parsen. Gebruik 201 Created bij een succesvolle aanmaak, 422 Unprocessable Content bij ongeldige input, 401 Unauthorized bij ontbrekende authenticatie, 404 Not Found bij een onbekende resource en 500 Internal Server Error bij een onverwachte fout aan de serverzijde. Correcte statuscodes maken error handling aan de clientzijde eenvoudiger en voorspelbaarder.
Foutmeldingen die helpen
Een foutmelding is een kans om de gebruiker van je API te helpen, geen straf. Een generieke {"error": "something went wrong"} zegt niets en dwingt de developer tot giswerk. Een goede foutresponse bevat een machineleesbare errorcode, een mensvriendelijke beschrijving en waar mogelijk een aanwijzing over hoe het op te lossen. Bijvoorbeeld: {"status": "error", "code": "users.23", "description": "Email is already in use"}. Of gebruik een gestandaardiseerde structuur zoals RFC 7807 — Problem Details for HTTP APIs — biedt een breed geaccepteerd formaat dat consistentie garandeert over alle endpoints heen en goed integreert met bestaande tooling.
Versionering vanaf dag één
Een API verandert mee met de software erachter, maar bestaande gebruikers mogen daar geen last van hebben. Versionering lost dat op door meerdere versies naast elkaar beschikbaar te houden. De meest gebruikte aanpak is een versienummer in de URL: /v1/users en /v2/users. Introduceer een nieuwe versie alleen bij breaking changes — wijzigingen die bestaande clients breken — en communiceer ruim van tevoren wanneer een oude versie wordt uitgefaseerd. Wie versionering overslaat in het begin, betaalt daar later een hoge prijs voor in migratiepijn en klantfrustatie.
Documentatie als eerste klasse burger
Een API zonder documentatie is een zwarte doos. Documentatie schrijven voelt als extra werk, maar het bespaart enorm veel tijd in de vorm van vragen, support en verkeerd gebruik. Tools zoals Swagger en OpenAPI maken het mogelijk om documentatie te genereren vanuit je code of spec-bestand, zodat het altijd up-to-date is. Voeg voorbeeldverzoeken en responses toe voor elk endpoint, beschrijf edge cases en documenteer authenticatie duidelijk. Goede documentatie is geen bijproduct van een goede API — het is een integraal onderdeel ervan.