Door Nathan Hannes

Inleiding en context

Dit artikel geeft een overzicht van de zaken waarmee rekening moet worden genomen bij het opzetten van webservices via het oData protocol, zowel betreffende de oData standaard zelf als de implementatie ervan in de tooling die gebruikt wordt voor het implementeren van de service.

Voordat we op oData inzoomen moeten we het eerst kort hebben over REST architectuur.
REST, of Representational State Transfer, werd opgezet als een architecturale standaard voor het bouwen van client-server network-based applicaties.

Hiervoor wordt op server level een abstractie gemaakt door te werken met resource-entity relaties waarbij een resource wordt gedefinieerd als elk ‘noembaar object’.

Er zijn 5 basisvoorwaarden gedefinieerd om aan de REST standaard te voldoen:

• Uniforme interface;
• Client-server design waarbij de UI wordt gescheiden van de data opslag (‘separation of concerns’);
• Stateless: elke client-server request moet op zichzelf staand de volledige informatie bevatten nodig om de aanvraag uit te voeren;
• Cacheability van response;
• Gelaagd systeem waarbij elke component enkel communiceert met de laag waarmee deze in interactie staat.

Onze focus hier ligt op web services waarbij gebruik wordt gemaakt van het HTTP protocol.
Elke web service die is opgebouwd volgens de REST architectuur kan worden geklasseerd als een ‘RESTful API’. Deze worden opgebouwd met een Uniform Resource Identifier (URI) die het resource pad aangeeft en de standaard HTTP methoden (GET/POST/PUT/DELETE).

OData, ofwel ‘Open Data Protocol’, is een standaard gebruikt voor het bouwen en gebruiken van RESTful APIs die door Microsoft in 2007 werd ontwikkeld en door OASIS gestandaardiseerd in 2014.

Het doel van oData is applicatiebouwers te helpen focussen op business logica in het bouwen van REST APIs zonder te veel rekening te moeten houden met request en response headers, complexe query syntax, specifieke HTTP methods, etc.

Een handige inleiding tot oData kan je hier vinden: Understand OData in 6 steps · OData – the Best Way to REST. Hier vindt je ook meer diepgaande informatie betreffende de standaard.

Voordelen en aandachtspunten bij het gebruik van oData

Een belangrijk voordeel bij het gebruik van oData is de intuïtieve opbouw van de request URLs. Ter illustratie, stel dat we een ‘Personen’ entity hebben die bestaat uit de volgende velden:

• ‘Naam’
• ‘Geboortedatum’
• ‘Maandloon’
• ‘Datum_tewerkstelling’
• ’Bedrijf_id’.

De belangrijkste beschikbare query opties zijn:

Filter

Hiermee kan gefilterd worden om de response enkel deze resources te doen teruggeven die voldoen aan de voorwaarde gespecifieerd in de filter, enkel voorbeelden:

http://host/service/Personen?$filter=Naam eq ‘Michiel’

• Enkel de records uit de entity (in dit geval een entity tabel Personen) waarbij ‘Naam’ overeenkomt met Michiel zullen worden opgenomen in de response

http://host/service/Personen?$filter=Naam ne ‘Michiel’

• Enkel de records uit de entity Personen waarbij ‘Naam’ niet overeenkomt met Michiel zullen worden opgenomen in de response

http://host/service/Personen?$filter=Maandloon ge 1000

• De records uit de entity Personen waarvoor ‘maandloon’ groter of gelijk is aan 1000 zullen worden teruggeven

Select

Select laat toe om binnen een entity enkel de velden te selecteren die gewenst zijn in de response, bijvoorbeeld:

http://host/service/Personen?$select=Naam

• enkel de Naam kolom in de entity zal in de response worden opgenomen

Deze kunnen ook gecombineerd worden:

http://host/service/Personen?$select=Naam&$filter=Maandloon ge 1000

• Enkel de Namen van de personen die een maandloon groter dan 1000 hebben zullen worden opgenomen in de respons.

Expand

Deze optie laat toe om queries op gerelateerde entities te combineren (vergelijkbaar met join in SQL).

Stel dat we naast “Personen” een entity ‘Bedrijf’ hebben die Naam en Locatie van bedrijven bevat waar personen zijn tewerkgesteld en dat de twee aan elkaar gelinkt zijn via ‘Bedrijf_id’, dan kunnen we als volgt requests opstellen:

http://host/service/Personen?$expand=Bedrijf&$filter= bedrijfsnaam eq ‘ABC’ &$select=Naam,Maandloon,Bedrijf/Naam

• Dit geeft alle Namen, maandlonen en bedrijfsnamen terug van de Personen die tewerkgesteld zijn in bedrijf ‘ABC’

Order By

Deze optie laat toe de resultaatset te ordenen op basis van een bepaald veld.

Top en Skip

Deze opties zijn belangrijk voor het implementeren van pagination, top laat toe enkel de bovenste ‘x’ (zelf te definiëren) records te selecteren, en skip laat toe een aantal records over te slaan. Door deze incrementeel te definiëren in de webservice kan men de resultaatset in stukken weergeven (bv. Top = 5, skip = 0  eerste 5 records worden weergegeven, top =5, skip=5: records 5-10 worden weergegeven).

Count

De count optie laat toe om naast de resultaatset ook het aantal records die in de resultaatset bevat zijn terug te geven, wat opnieuw nuttig is voor pagination (om te weten over hoeveel records in totaal moet worden geïtereerd).

Voor een volledig overzicht van de query- en filteropties, zie OData Version 4.01. Part 1: Protocol (oasis-open.org)

Nadelen bij het gebruik van oData in webapplicaties

Security

Aangezien we enkel met URLs werken bij oData is het belangrijk na te denken over hoe de security wordt geïmplementeerd.

Limitaties

Afhankelijk van de tools die worden gebruikt om oData web service te implementeren kunnen er limitaties zijn in de query mogelijkheden (dit is eerder een nadeel van specifieke oData implementaties in tooling dan oData zelf, we komen hier later op terug);

Kennis

Bij het gebruik van oData web services is het doorgaans vereist reeds een goede kennis te hebben van de achterliggende data structuur en relaties tussen de entities (documentatie is zeer belangrijk).

Wil je meer weten over oData of het gebruik ervan?
Contacteer ons via nathan.hannes@juvo.be

Wij helpen jou graag verder om jouw data nog beter te gebruiken.