Soorten API's: REST, SOAP, GraphQL en waarom JSON de standaard is.

Niet elke API is hetzelfde

Als je twee systemen met elkaar wilt laten praten, heb je een API nodig. Maar API is een breed begrip. Er zijn verschillende stijlen, protocollen en authenticatiemethoden. De keuze die je maakt heeft directe impact op de snelheid van implementatie, de kosten en het onderhoud op lange termijn.

In dit artikel nemen we de belangrijkste API-types door, hoe authenticatie werkt, waarom documentatie het verschil maakt tussen een professionele en een amateuristische koppeling, en waarom versioning onmisbaar is zodra je API in productie draait.

REST: de moderne standaard

REST staat voor Representational State Transfer. Het is geen protocol maar een architectuurstijl die gebruik maakt van standaard HTTP-methoden: GET om data op te halen, POST om aan te maken, PUT of PATCH om te wijzigen, en DELETE om te verwijderen. Data wordt uitgewisseld in JSON-formaat.

REST is veruit de meest gebruikte API-stijl voor moderne software. Vrijwel elke SaaS-applicatie, betaalprovider en cloud-dienst biedt een REST API aan. De reden: het is simpel, voorspelbaar en snel te implementeren. Een developer die REST kent, kan binnen uren de eerste calls maken naar een goed gedocumenteerde API.

Waarom REST werkt

• Lichtgewicht — geen overbodige envelopes of headers. Je stuurt JSON, je krijgt JSON terug.
• Standaard HTTP — elke programmeertaal en elk framework ondersteunt HTTP out of the box.
• Stateless — elk verzoek bevat alle informatie die de server nodig heeft. Geen sessies, geen complexe state management.
• Schaalbaar — door het stateless karakter kun je eenvoudig horizontaal schalen.

SOAP: het verleden dat blijft hangen

SOAP staat voor Simple Object Access Protocol, al is er niets simpels aan. SOAP werkt met XML als dataformaat en verpakt elk bericht in een envelope met een header en body. Het is een strikt protocol met vaste regels, schema's en een WSDL-bestand (Web Services Description Language) dat beschrijft wat de API kan.

SOAP was de standaard in de jaren 2000 en komt nog steeds voor bij legacy-systemen, banken, overheden en grote enterprise-applicaties. Als je koppelt met een oud ERP-systeem of een overheids-API, is de kans groot dat je SOAP tegenkomt.

Waarom SOAP achterhaald is

• XML is verbose — dezelfde data in XML is twee tot drie keer zo groot als in JSON. Meer data betekent meer bandbreedte en langzamere responses.
• Complexe implementatie — het parsen van XML-envelopes, het valideren tegen XSD-schema's en het afhandelen van SOAP-faults kost aanzienlijk meer ontwikkeltijd dan een REST-call met JSON.
• Hogere kosten — meer ontwikkeltijd betekent direct hogere kosten. Een SOAP-integratie kost al snel twee tot drie keer zoveel als dezelfde koppeling via REST.
• Minder tooling — moderne frameworks en libraries zijn geoptimaliseerd voor JSON en REST. SOAP-tooling bestaat, maar is minder actief onderhouden en minder intuïtief.

SOAP en XML zijn niet per definitie slecht — maar ze zijn wel duurder, trager en complexer. Als je de keuze hebt, kies je REST met JSON. Altijd.

GraphQL: flexibel maar niet altijd nodig

GraphQL is ontwikkeld door Meta en laat de client bepalen welke data hij precies nodig heeft. In plaats van vaste endpoints stuur je een query die beschrijft welke velden je wilt ontvangen. Dit voorkomt over-fetching (te veel data ophalen) en under-fetching (te weinig data, waardoor je extra requests moet doen).

GraphQL is krachtig voor complexe applicaties met veel geneste data, zoals social media platforms of dashboards die data uit meerdere bronnen combineren. Voor de meeste zakelijke koppelingen — facturen synchroniseren, orders doorzetten, klantdata ophalen — is REST meer dan voldoende en eenvoudiger te implementeren.

Authenticatie: wie mag aankloppen?

Elke API moet weten wie er verbinding maakt en welke rechten die partij heeft. Er zijn verschillende methoden, elk met hun eigen afwegingen.

API keys

De eenvoudigste methode. Je ontvangt een unieke sleutel die je meestuurt in de header van elk verzoek. De server herkent je aan die sleutel en geeft toegang. Simpel en effectief voor server-naar-server communicatie.

Het nadeel: een API key is een statisch geheim. Als de sleutel uitlekt, heeft iemand volledige toegang totdat je de key intrekt en een nieuwe genereert. Er is geen granulaire controle over wat iemand met die key mag doen, tenzij de API-provider dit apart heeft ingebouwd.

OAuth 2.0

De standaard voor integraties waarbij een gebruiker expliciet toestemming geeft. De gebruiker logt in bij de externe dienst, autoriseert jouw applicatie, en je ontvangt een access token (korte levensduur) en een refresh token (lange levensduur). Het access token gebruik je voor API-calls; het refresh token om een nieuw access token op te halen als het oude verloopt.

OAuth is veiliger: tokens verlopen automatisch, de gebruiker kan toestemming intrekken, en je hoeft geen wachtwoorden op te slaan. Platforms als Exact Online, Moneybird en Google gebruiken allemaal OAuth 2.0. De implementatie is complexer, maar voor professionele koppelingen is het de juiste keuze.

Bearer tokens en JWT

Een bearer token is een tijdelijk bewijs van authenticatie dat je meestuurt in de Authorization-header. JWT (JSON Web Token) is een specifiek formaat waarbij het token zelf informatie bevat over de gebruiker en zijn rechten, beveiligd met een digitale handtekening. De server hoeft geen database te raadplegen om het token te valideren — hij verifieert simpelweg de handtekening.

Basic Authentication

De meest primitieve methode: je stuurt een gebruikersnaam en wachtwoord mee bij elk verzoek, gecodeerd in Base64. Dit is alleen acceptabel over HTTPS en eigenlijk alleen geschikt voor interne of test-API's. Voor productieomgevingen is het te kwetsbaar.

JSON vs XML: de data-taal maakt uit

Het dataformaat waarin een API communiceert is niet slechts een technisch detail. Het heeft directe impact op de ontwikkeltijd, de leesbaarheid en de performance van je koppeling.

JSON (JavaScript Object Notation) is compact, leesbaar en native ondersteund door vrijwel elke moderne programmeertaal. Het parsen van JSON is snel en eenvoudig. XML daarentegen is verbose, vereist speciale parsers en maakt foutopsporing lastiger door de geneste structuur met open- en sluittags.

Een praktisch voorbeeld: dezelfde klantgegevens in JSON zijn ongeveer 40% kleiner dan in XML. Bij duizenden API-calls per dag scheelt dat in bandbreedte, verwerkingstijd en kosten.

JSON is de taal van het moderne web. Als een API nog uitsluitend XML spreekt, is dat een signaal dat de onderliggende software toe is aan modernisering.

HTTP-statuscodes: de taal van foutafhandeling

Een van de meest onderschatte aspecten van een goede API zijn HTTP-statuscodes. Ze vormen een gestandaardiseerde manier om aan te geven wat er met een verzoek is gebeurd, zonder dat je de response-body hoeft te parsen.

Waarom statuscodes onmisbaar zijn

• 200 OK — het verzoek is gelukt.
• 201 Created — een nieuw record is succesvol aangemaakt.
• 400 Bad Request — de request bevat ongeldige data.
• 401 Unauthorized — je bent niet geauthenticeerd.
• 403 Forbidden — je bent geauthenticeerd maar hebt geen rechten.
• 404 Not Found — de resource bestaat niet.
• 422 Unprocessable Entity — de data is syntactisch correct maar semantisch ongeldig (validatiefout).
• 429 Too Many Requests — je hebt de rate limit overschreden.
• 500 Internal Server Error — er ging iets mis aan de serverkant.

Het probleem met API's die alles als 200 teruggeven

Sommige API's geven altijd een 200-statuscode terug, ook als het verzoek mislukt. De foutmelding zit dan verstopt in de response-body. Dit is een van de meest frustrerende anti-patterns in API-design. Je moet de hele response parsen, zoeken naar een error-veld, en dan pas bepalen of het gelukt is.

Dit is omslachtig, foutgevoelig en kost extra ontwikkeltijd. Een goede API gebruikt de juiste statuscode zodat je foutafhandeling direct op het HTTP-niveau kunt regelen — snel, betrouwbaar en gestandaardiseerd.

Documentatie: het verschil tussen professioneel en amateuristisch

De kwaliteit van API-documentatie is misschien wel de beste indicator van de kwaliteit van de API zelf. Goede documentatie maakt het verschil tussen een koppeling die in dagen staat en een die weken of maanden kost.

Wat goede documentatie bevat

• Alle endpoints — een volledig overzicht van wat de API kan, inclusief URL's, HTTP-methoden en parameters.
• Request- en response-voorbeelden — concrete JSON-voorbeelden van wat je stuurt en wat je terugkrijgt.
• Authenticatie-instructies — stap-voor-stap uitleg hoe je verbinding maakt, inclusief voorbeeldcode.
• Foutcodes en foutmeldingen — een overzicht van alle mogelijke fouten, wat ze betekenen en hoe je ze oplost.
• Rate limits — hoeveel verzoeken je mag doen en wat er gebeurt als je de limiet overschrijdt.
• Changelog — wat er veranderd is per versie, zodat je weet of een update impact heeft op jouw koppeling.

Rode vlaggen bij documentatie

Een API zonder documentatie, of met alleen een simpel PDF'je van twee pagina's, is bijna altijd een signaal van een onprofessionele koppeling. Het betekent dat de aanbieder niet heeft nagedacht over de developer experience en dat je als implementerend team veel meer tijd kwijt bent aan uitzoekwerk, trial-and-error en contact met de aanbieder.

Professionele API's bieden interactieve documentatie via tools als Swagger (OpenAPI), Postman of ReadMe. Je kunt endpoints direct testen, voorbeelden kopiëren en foutscenario's simuleren. Hoe beter de documentatie, hoe sneller en goedkoper de implementatie.

Geen documentatie? Dan is de API waarschijnlijk net zo slordig gebouwd als de documentatie die ontbreekt.

Versioning: je API verandert, je klanten niet

Een API die in productie draait, wordt gebruikt door andere systemen die afhankelijk zijn van het huidige gedrag. Als je de structuur van een response wijzigt, een veld hernoemt of een endpoint verwijdert, breek je potentieel alle koppelingen die daarvan afhankelijk zijn.

Versioning lost dit op. Door je API een versienummer te geven (bijvoorbeeld /api/v1/ en later /api/v2/) kunnen bestaande koppelingen blijven werken op de oude versie terwijl nieuwe integraties de nieuwste versie gebruiken.

Best practices voor versioning

• Versie in de URL — de meest gangbare methode. Duidelijk, expliciet en eenvoudig te implementeren.
• Oude versies niet direct uitfaseren — geef klanten en partners voldoende tijd om over te stappen. Communiceer deprecation ruim van tevoren.
• Changelog bijhouden — documenteer per versie wat er veranderd is, wat er nieuw is en wat er verwijderd wordt.
• Breaking changes alleen in nieuwe major versies — kleine toevoegingen (een nieuw veld) kunnen in de huidige versie. Wijzigingen die bestaande integraties breken, horen in een nieuwe versie.

Zonder versioning wordt elke wijziging aan je API een risico. Met versioning kun je je API doorontwikkelen zonder bestaande koppelingen te breken.

Hoe Coding Agency API's bouwt

Bij Coding Agency ontwikkelen wij uitsluitend REST API's met JSON als dataformaat. Niet omdat het trendy is, maar omdat het de meest efficiënte, best ondersteunde en meest kosteneffectieve keuze is voor vrijwel elke zakelijke toepassing.

Onze API's volgen vaste standaarden:

• REST met JSON — geen XML, geen SOAP. Compact, snel en universeel ondersteund.
• HTTP-statuscodes als standaard — de juiste statuscode bij elke response, zodat foutafhandeling gestandaardiseerd en betrouwbaar is.
• Uitgebreide documentatie — interactieve API-documentatie met voorbeelden, foutcodes en authenticatie-instructies. Geen PDF'je, maar een volledige developer experience.
• Versioning vanaf dag één — elke API start met een versienummer, zodat je later kunt doorontwikkelen zonder bestaande koppelingen te breken.
• OAuth 2.0 of API keys — afhankelijk van het scenario de juiste authenticatiemethode, veilig en goed gedocumenteerd.

Of je nu een eigen API nodig hebt voor je platform, een koppeling wilt bouwen met een extern systeem of een bestaande SOAP-integratie wilt moderniseren naar REST: wij zorgen dat het professioneel, schaalbaar en goed onderhoudbaar is.