OData en de REST API Design Rules: past dat wel?

21 oktober 2025 · 8 minuten leestijd

Implementatie ondersteuner - developer.overheid.nl

Binnen de publieke sector groeit de behoefte aan goed gedocumenteerde, interoperabele en toekomstbestendige API's. De REST API Design Rules (ADR) vormen daarbij een belangrijk referentiekader: ze stimuleren eenvoud, voorspelbaarheid en brede toepasbaarheid door gebruik te maken van open standaarden.

Regelmatig komt de vraag voorbij of OData, een specificatie ontwikkeld binnen het Microsoft-ecosysteem, een slimme keuze kan zijn voor publieke API's. In dit artikel analyseren we de voor- en nadelen van OData, met nadruk op eenvoud, interoperabiliteit en vendor-neutraliteit. Ook bekijken we hoe OData zich verhoudt tot de ADR, en op welke vlakken deze conflicteren.

Logo of OData

Wat is OData?

OData (Open Data Protocol) is een open standaard die definieert hoe data via RESTful API's kan worden bevraagd en gemanipuleerd. Het biedt een gestandaardiseerde manier om queries uit te voeren op resources, met parameters als $filter, $expand, $select en $orderby.

OData is oorspronkelijk ontwikkeld door Microsoft en gestandaardiseerd via OASIS en ISO/IEC, wat betekent dat het formeel gezien niet proprietair is. In de praktijk is de implementatie en tooling echter sterk verweven met Microsoft-technologieën (zoals .NET, Dynamics en Power BI).

De voordelen van OData

1. Gestandaardiseerde querytaal

Middels het OData protocol kan een client complexe queries uitvoeren (zoals filters, joins en sorteringen) zonder dat de API-beheerder expliciet endpoints of parameters hoeft te definiëren voor elk scenario. In plaats van meerdere, specifieke zoek- en filterendpoints aan te bieden, kan een OData-service via één uniforme syntax ($filter, $expand, $select, $orderby, enz.) vrijwel elke denkbare bevraging verwerken.

Dat maakt OData efficiënt bij situaties waarin de aard van de queries niet vooraf bekend is, bijvoorbeeld bij analytische toepassingen, datawarehouses of BI-rapportages. Daarmee biedt OData een zekere mate van zelfbediening voor dataconsumenten – iets wat in interne dataplatforms of onderzoeksomgevingen vaak als voordeel wordt gezien.

2. Rijke semantische laag

OData beschrijft de datastructuur via het Entity Data Model (EDM), vastgelegd in CSDL (Common Schema Definition Language) via JSON of XML. Dit maakt het mogelijk om data en relaties semantisch te beschrijven.

Clients worden hierdoor in staat gesteld om automatisch metadata te ontdekken en hun gedrag daarop af te stemmen. Een client kan bijvoorbeeld aan de hand van het $metadata-document weten welke velden beschikbaar zijn, welke typen of relaties er bestaan en welke queries toegestaan zijn.

Dit bevordert consistentie en herbruikbaarheid van data binnen een organisatie, en ondersteunt scenario's als automatische codegeneratie, dynamische UI-componenten of semantische validatie. Voor organisaties met sterk gestructureerde domeinmodellen kan dit bijdragen aan uniformiteit en ontwerpdiscipline over verschillende datasets heen.

3. Sterke toolingondersteuning (met name in Microsoft-omgevingen)

OData is wijd geïntegreerd in de Microsoft-stack en wordt ondersteund door veelgebruikte producten zoals Excel, Power BI en Azure API Management. In de praktijk betekent dit dat gegevens uit een OData-service direct bruikbaar zijn in rapportage-, analyse- of dashboardomgevingen, met minimale technische inspanning.

De nadelen van OData

1. Data-georiënteerd in plaats van resource-georiënteerd

OData is in de kern data-georiënteerd: het beschrijft tabellen en entiteiten die rechtstreeks overeenkomen met een onderliggend datamodel. Daarmee verschilt het fundamenteel van de resource-georiënteerde aanpak die in de ADR wordt voorgestaan, waarin endpoints domeinconcepten representeren (zoals zaak, persoon of vergunning), niet technische datatabellen.

In de praktijk leidt dat tot API-ontwerpen waarin de datastructuur het uitgangspunt vormt, in plaats van het functionele of semantische domein. Dit maakt de API minder begrijpelijk en minder consistent met andere publieke API's die wel volgens de REST-principes zijn ontworpen.

Hoewel OData zich positioneert als RESTful, wijkt het in de praktijk af van gangbare REST-ontwerpprincipes. De query-syntax (voor $filter, $expand, enz.) introduceert een eigen mini-taal bovenop HTTP. Dit maakt het moeilijker om de API intuïtief te gebruiken en te documenteren volgens de ADR, die juist eenvoud en voorspelbaarheid benadrukken.

2. Compatibiliteit met de OpenAPI Specification

De ADR vereisen een API-beschrijving conform de OpenAPI Specification. Hoewel OData services formeel op die manier kunnen worden beschreven, genereren veel OData-servers primair een eigen $metadata-document (CSDL) in plaats van een OpenAPI-document.

Een vertaling van CSDL naar OpenAPI is mogelijk – en zelfs gestandaardiseerd – maar niet zonder verlies van semantiek. Wanneer CSDL naar OpenAPI wordt vertaald, gaan de semantische beperkingen en validatieregels van filters en expressies verloren. OpenAPI kan alleen weergeven dat er query parameters zijn, maar niet wat hun gedrag is; dat is tenslotte vastgelegd in externe OData-specifieke standaarden. Dit beperkt de interoperabiliteit met bestaande ontwikkel- en documentatietools.

3. Beleidsmatige en interoperabiliteitsoverwegingen

Binnen de publieke sector neemt de behoefte toe aan samenhang tussen open standaarden. De Nederlandse overheid streeft dan ook naar een coherent API-stelsel waar open standaarden, profielen en architectuurprincipes samenkomen. Denk hierbij bijvoorbeeld aan interoperabiliteit tussen initiatieven zoals DCAT-AP-NL, OGC API en modelleringsstandaarden zoals MIM en NL-SBB.

OData vormt in dat opzicht een eigen ecosysteem, met een afwijkend query- en metadatamodel (CSDL) en een eigen set tools. Daardoor sluit het minder goed aan op bestaande Nederlandse en Europese API-profielen en beperkt het de mogelijkheid om gemeenschappelijke tooling of documentatie te hergebruiken. Voor organisaties die streven naar maximale interoperabiliteit binnen publieke stelsels is dit een belangrijk aandachtspunt.

4. Vendor-afhankelijkheid in tooling en adoptie

OData is strict genomen een open standaard, maar de praktische adoptie concentreert zich sterk binnen het Microsoft-ecosysteem. De meeste volwassen implementaties, libraries en client-SDK's zijn Microsoft-georiënteerd. Buiten deze omgeving is de ondersteuning beperkter: veel open source-projecten zijn verouderd of incompleet, en de community is kleiner dan die rond OpenAPI, JSON Schema of andere relevante standaarden.

Rond de OpenAPI-specificatie bestaat een rijk ecosysteem aan tools – van validators en mockservers tot SDK-generators en testframeworks. Veel daarvan werken echter niet, of slechts beperkt, met OData, omdat een groot deel van de OData-details niet in OpenAPI-formaat kan worden uitgedrukt.

Voor organisaties die streven naar vendor-neutraliteit en technologie-onafhankelijkheid is dit een belangrijk aandachtspunt. Wie OData kiest, wordt niet formeel locked-in door de standaard zelf, maar wel door de beschikbare tooling, kennis en infrastructuur die vooral door één leverancier wordt gedomineerd. Dit kan migratie, integratie met niet-Microsoft-omgevingen en aansluiting bij bredere open API-ecosystemen bemoeilijken.

5. Moeilijk te beheersen expressiviteit

OData biedt krachtige en zeer expressieve querymogelijkheden, waarmee clients complexe filters, sorteringen en uitbreidingen kunnen uitvoeren via $filter, $expand, $select en $orderby. Die expressiviteit is aantrekkelijk bij data-analyse, maar brengt in publieke API's aanzienlijke complexiteit met zich mee, zowel aan de server- als aan de clientzijde.

Aan de serverzijde betekent dit dat de API elke ontvangen query dynamisch moet kunnen interpreteren en vertalen naar een onderliggende database-query. Daarbij kunnen onverwacht zware of inefficiënte combinaties ontstaan, bijvoorbeeld geneste $expand-queries of samengestelde $filter-expressies met meerdere or- en any-operatoren. Om dit te beheersen zijn vaak aanvullende maatregelen nodig, zoals query throttling, expressielimieten, caching, of specifieke middleware die de toegestane querypatronen begrenst. Zonder dergelijke beperkingen kan de server onvoorspelbare performance vertonen of zelfs kwetsbaarheden introduceren, zoals denial-of-service-achtige situaties.

Aan de clientzijde leidt dezelfde flexibiliteit tot hogere implementatiecomplexiteit. Een OData-client moet de volledige querysyntaxis ondersteunen en correct kunnen omgaan met foutmeldingen, datamodelverwijzingen en dynamische metadata uit het $metadata-document. Dat vraagt om specifieke libraries en kennis van de OData-taal zelf, wat de drempel verhoogt ten opzichte van eenvoudigere, parametergebaseerde REST-API's. Zelfs kleine implementatieverschillen tussen OData-versies of servers kunnen tot interoperabiliteitsproblemen leiden.

Voor publieke API's is deze expressieve kracht dus zowel een voordeel als een risico. Het gebruik ervan vraagt om duidelijke ontwerpkeuzes, restricties en beheermaatregelen om de balans te bewaren tussen flexibiliteit en controle.