OData API

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

Image

Het opstellen van een query bestaat uit het kiezen van een entiteitsoort als beginpunt en het toevoegen van functies met argumenten om zo tot de gewenste resultaten te komen. Wanneer er geen functies toegevoegd worden aan een query zullen alle entiteiten van een entiteitsoort getoond worden.

Om de data van een specifieke entiteit te tonen kan de waarde van het attribuut id gebruikt worden. 

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.

Ga naar de officiële documentatie van OData

Image

Om functies toe te voegen aan een query dient een ? toegevoegd te worden achter de entiteitsoort of de specifieke entiteit die als beginpunt is gekozen. Ieder daaropvolgende functie dient te beginnen met &, en de argumenten van een functie komen achter een =. 

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. 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. Het is aan te raden om altijd te filteren op entiteiten die niet zijn verwijderd daar verwijderde entiteiten als placeholder in het Gegevensmagazijn blijven bestaan om wijzigingen te kunnen herleiden.

Met de operatoren startswith(), endswith() en contains() als argument van de functie $filter kan op gedeeltes van de waarde van een bepaald attribuut gefilterd worden.

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

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. 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() dient gebruikt te worden wanneer één van de gerelateerde entiteiten door de filter heen moet komen om een entiteit in de resultaten te laten zien.

De operator all() dient gebruikt te worden 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 getoond worden. Deze functie kan onder andere ingezet worden om de grootte van de resultaten te beperken daar standaard alle attributen getoond worden.

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 dient een ; gebruikt te worden 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.

Image

Nog vragen? Kijk bij de veelgestelde vragen of het antwoord erop er al bijstaat.