OData API

Om zoekvragen te kunnen maken voor de OData API gebruik je een URL waar je parameters aan toevoegt. Het is belangrijk dat je daarvoor de meest recente versie gebruikt:

Het datamodel dat gebruikt wordt in de OData API is gelijk aan het informatiemodel van het Gegevensmagazijn. Het informatiemodel geeft een overzicht van alle entiteitsoorten die opgevraagd kunnen worden middels de OData API en hun onderlinge relaties. Op de detailpagina's van de entiteitsoorten is te zien welke attributen een entiteit van een bepaalde entiteitsoort heeft en worden voorbeelden gegeven.

Ga naar de documentatiepagina over het informatiemodel.

Het opstellen van een zoekvraag, een query, bestaat uit het twee delen? Eerst kies je een entiteitsoort (bijvoorbeeld een persoon of document) als beginpunt. Daar voeg je functies met argumenten (zoals een datumfilter) aan toe. 

Wanneer je geen functies toevoegt aan een query,  zie je in de resultaten alle entiteiten van die entiteitsoort:

Om de data van een specifieke entiteit te tonen kan je de waarde van het attribuut id gebruiken. Dit id vind je alleen in het zoekresultaat van een eerdere opdracht. Met het kan je id kan je meer informatie verkrijgen over een document.

Wanneer een specifieke entiteit een achterliggend bestand heeft, kan deze worden opgehaald door /resource aan de query toe te voegen:

Bekijk ook de documentatie op de website van OData voor meer informatie over het opstellen van queries.

Om functies toe te voegen aan een query, voeg je een ? toe achter de entiteitsoort of de specifieke entiteit die als beginpunt is gekozen. Ieder daaropvolgende functie geef je aan met &, en de argumenten van een functie komen achter een =. In de voorbeelden hieronder zie je hoe dit werkt.

Filteren op attributen met $filter

De functie $filter maakt het mogelijk om de resultaten van een query te filteren op basis van de waardes van attributen. Denk daarbij aan een datum of naam. In de argumenten van $filter kunnen vergelijkingsoperatoren (eq, ne, gt, lt, ge, le) en Booleaanse operatoren (and, or, not) gebruikt worden om de resultaten te vernauwen of verruimen. Lees meer over deze operatoren en wanneer je welke gebruikt.

Het is aan te raden om altijd te filteren op entiteiten die niet zijn verwijderd omdat verwijderde entiteiten als placeholder in het Gegevensmagazijn blijven bestaan om wijzigingen te kunnen herleiden. Door te filteren op niet-verwijderede entiteiten komen de placeholders dus niet bij de resultaten.

In de volgende voorbeelden zie je hoe je filters kan gebruiken:

Met de operatoren startswith(), endswith() en contains() als argument van de functie $filter kan je op gedeeltes van de waarde van een bepaald attribuut filteren:

Voor het filteren met datums in argumenten van de functie $filter zijn er de operatoren second(), minute(), day(), hour(), month() en year():

Filteren met $filter bij gerelateerde entiteiten

Als een entiteit een relatie heeft met entiteiten van een andere entiteitsoort, kan de oorspronkelijke entiteit gefilterd worden op basis van de waardes van attributen van de gerelateerde entiteitsoort. In de voorbeelden hieronder kan je zien hoe dat werkt.

Bij op-één-relaties kan er gefilterd worden door in de functie $filter met een / te verwijzen naar de gerelateerde entiteitsoort en het attribuut:

Bij op-veel-relaties kan er gefilterd worden door in de functie $filter gebruik te maken van de operatoren any() en all(). 

De operator any() gebruik je wanneer één van de gerelateerde entiteiten door de filter heen moet komen om een entiteit in de resultaten te laten zien:

De operator all() gebruik je wanneer alle gerelateerde entiteiten door de filter heen moeten komen om een entiteit in de resultaten te laten zien:

Attributen van resultaten beperken met $select

De functie $select maakt het mogelijk om te kiezen welke attributen van een entiteit in de resultaten komen. Met deze functie kan je de grootte van de resultaten beperken, omdat je niet alle attributen meeneemt.

Gerelateerde entiteiten ophalen met $expand

De functie $expand maakt het mogelijk om bij een entiteit alle gerelateerde entiteiten van een andere entiteitsoort te tonen in de resultaten. Het is mogelijk om binnen een $expand door middel van ( ) functies toe te passen op de resultaten van de $expand. Om meerdere functies toe te passen op de resultaten van een $expand gebruik je een ;  in plaats van een &.

Resultaten overslaan met $skip

De functie $skip maakt het mogelijk om een bepaald aantal resultaten over te slaan. Om de belasting van individuele queries op het Gegevensmagazijn te minimaliseren worden standaard maximaal 250 resultaten tegelijkertijd weergegeven. Dit geldt ook voor het aantal entiteiten dat met de functie $expand opgehaald kan worden. Wanneer een query meer dan 250 resultaten geeft staat er onderaan de pagina een query die leidt naar de volgende pagina.

Resultaten beperken met $top

De functie $top maakt het mogelijk om het aantal resultaten te beperken.

Resultaten sorteren met $orderby

De functie $orderby maakt het mogelijk om de resultaten te sorteren op basis van de waarde van een attribuut. De argumenten asc (oplopend) en desc (aflopend) kunnen gebruikt worden om de volgorde te bepalen. 

Resultaten tellen met $count

De functie $count maakt het mogelijk om het totaal aantal resultaten te weergeven. De argumenten van de functies $skip en $top worden hierbij genegeerd.

Het metadataniveau bepalen met $format

De functie $format maakt het mogelijk om in te stellen hoeveel metadata van entiteiten getoond wordt. Er zijn drie metadataniveaus beschikbaar: none, minimal en full. De extra metadata helpen bij het beter begrijpen van een entiteitsoort (beschikbare argumenten voor de functie $expand, achterliggende bestanden, etc.). In productie is het aan te raden om gebruik te maken van het metadataniveau none om de grootte van de resultaten te beperken.

Heb je na het lezen van deze documentatie nog vragen? Kijk eerst bij de veelgestelde vragen of neem anders contact op.