OData API 2.0
Open Data Protocol (OData) versie 4 is een open protocol voor het ontwikkelen van REST API’s. OData wordt in veelgebruikte applicaties zoals bijv. Excel en Microsoft Power BI standaard ondersteund als bron. Er is op het internet veel informatie beschikbaar voor ontwikkelaars hoe OData API’s bevraagd kunnen worden. Het OData protocol leent zich goed om een snapshot van verschillende entiteiten in samenhang op te kunnen halen met behulp van een enkele zoekvraag. Via de OData v4 API kan informatie opgevraagd worden in JSON formaat.
Er is op internet veel informatie beschikbaar voor ontwikkelaars hoe OData API's bevraagd kunnen worden. Hieronder vindt u enkele handige (Engelstalige) links over OData:
| # | URL | OData versie | API-data versie | Opmerkingen |
|---|---|---|---|---|
|
1 |
/OData/v4/2.0/ |
4 (json) |
2.0 |
Maakt gebruik van OData v4 protocol, deze ondersteunt JSON. |
De volledige URL van de OData v4 API is:
https://gegevensmagazijn.tweedekamer.nl/OData/v4/2.0/
Datamodel OData
De data in OData komt overeen met het informatiemodel. Gegevens in OData zijn anders gemodelleerd dan in de SyncFeed. De SyncFeed is gebaseerd op XML opslag, OData slaat de data relationeel op. Per entiteit krijgt u steeds uitbreidingsmogelijkheden (expands) om gerelateerde data uit andere entiteiten erbij te zoeken.
| OData entiteiten | Opmerkingen |
|---|---|
|
Activiteit |
|
|
ActiviteitActor |
|
|
Agendapunt |
|
|
Besluit |
|
|
Commissie |
|
|
CommissieContactinformatie |
|
|
CommissieZetelVastPersoon |
|
|
CommissieZetelVastVacature |
|
|
CommissieZetelVervangerPersoon |
|
|
CommissieZetelVervangerVacature |
|
|
CommissieZetel |
|
|
Document |
Inclusief download link naar bestand: doc(x)/pdf. |
|
DocumentActor |
|
|
DocumentVersie |
|
|
Fractie |
(Optioneel) |
|
FractieAanvullendGegeven |
|
|
FractieZetel |
|
|
FractieZetelPersoon |
|
|
FractieZetelVacature |
|
|
Kamerstuk |
|
|
Kamerstukdossier |
|
|
Persoon |
(Optioneel) |
|
PersoonContactinformatie |
|
|
PersoonGeschenk |
|
|
PersoonLoopbaan |
|
|
PersoonNevenfunctie |
|
|
PersoonNevenfunctieInkomsten |
|
|
PersoonOnderwijs |
|
|
PersoonReis |
|
|
Reservering |
|
|
Stemming |
|
|
Vergadering |
|
|
Verslag |
Inclusief download link naar volledige XML. |
|
Zaak |
|
|
ZaakActor |
|
|
Zaal |
Algemene kolommen
De entiteiten hebben allen de volgende kolommen:
| Kolomnaam | Opmerkingen |
|---|---|
|
Id |
GUID (Globally Unique Identifier) van de entiteit. |
|
GewijzigdOp |
Datum wanneer het bronsysteem deze entiteit heeft aangemaakt/aangepast. |
|
ApiGewijzigdOp |
Datum wanneer deze entiteit (mutatie) zichtbaar is geworden in de OData API. Filteren op dit veld maakt het mogelijk om alleen verschillen op te halen van een bepaalde periode. |
|
Verwijderd |
Komt overeen met verwijderd=true/false op entiteit niveau uit de SyncFeed. Er is bewust voor gekozen alle verwijderde entiteiten als “placeholder” zichtbaar te houden in de API zodat afnemers kunnen detecteren wanneer iets verwijderd is. Wanneer u enkel bestaande entiteiten wilt opvragen dient u zelf te filteren op “Verwijderd eq false”. |
Query voorbeelden
OData heeft een eigen querytaal voor het opvragen van data. Hieronder staan een aantal queries om mee te beginnen:
| Omschrijving | Query |
|---|---|
| Algemeen: opvragen beschikbare entiteiten en functies | /$metadata |
| Opvragen commissieleden (Afkorting nu op FIN) | /Persoon?$expand=CommissieZetelVastPersoon, CommissieZetelVastPersoon($expand=CommissieZetel($expand=Commissie))&$orderby=Achternaam&$filter=CommissieZetelVastPersoon/any(aa: aa/CommissieZetel/Commissie/Afkorting eq 'FIN' and aa/TotEnMet eq null) |
| Opvragen actieve Kamerleden van een fractie | Persoon?$filter=FractieZetelPersoon/any(a:a/FractieZetel/Fractie/Afkorting eq '<<afkorting hier invullen>>') and FractieZetelPersoon/any(a:a/TotEnMet eq null)&$expand=FractieZetelPersoon($expand=FractieZetel($expand=Fractie))&$format=application/json;odata.metadata=full |
| Kamerleden: alle actieve | /Persoon?$orderby=Achternaam&$filter=FractieZetelPersoon/any(a:a/TotEnMet eq null)&$expand=FractieZetelPersoon($expand=FractieZetel($expand=Fractie))&$count=true |
| Activiteiten: per vergaderjaar | /Activiteit?$filter=Vergaderjaar eq '2015-2016'&$orderby=Aanvangstijd desc |
| Parlementaire documenten: moties, zoek in onderwerp (voorbeeld ‘beveiliging’) | /Document?$filter=Soort eq 'Motie' and contains(Onderwerp,'beveiliging') |
| Activiteiten opvragen van een bepaalde maand (voorbeeld mei 2019) | /Activiteit?$filter=year(Aanvangstijd) eq 2019 and month(Aanvangstijd) eq 5&$orderby=Aanvangstijd desc |
| Geef de vergaderingen met links naar de verslagen uit 2017-2008 in JSON formaat en oplopend gesorteerd op Begin. |
/Vergadering?$expand=Verslag&$filter=Vergaderjaar eq '2018-2019'&$orderby=Datum desc&$format=application/json;odata.metadata=full |
| Document download |
/Document?$format=application/json;odata.metadata=full&$filter=DocumentNummer eq '2009D35955' |
| Persoon afbeelding download (optioneel) |
/Persoon?$orderby=Achternaam&$filter=Achternaam eq 'Pechtold'&$format=application/json;odata.metadata=full |
| Per kamerstukdossier de activiteiten opvragen waar deze in behandeld is. | /Zaak?$filter=Agendapunt/any(a:a ne null) and Kamerstukdossier/any(d: d/Nummer eq 34986) and Verwijderd eq false&$format=application/json;odata.metadata=full&$expand=Agendapunt($expand=Activiteit) |
(Let op: u moet het adres van het end-point voor de query plaatsen. Bijvoorbeeld: https://gegevensmagazijn.tweedekamer.nl/OData/v4/2.0/)
De volgende functies zijn universeel te gebruiken in de queries:
| Functie | v4 |
|---|---|
| expand | $expand=Besluit($expand=Agendapunt($expand=Activiteit)) |
| entiteiten tellen | $count=true |
| pagineren | $skip=250 |
| filteren op datum | $filter=Datum gt 2017-01-01T00:00:00Z |
| filteren op datum/tijd/tijdzone | $filter=Datum gt 2019-03-07T00:00:00%2B01:00 (waarbij de plus (+) van de tijdzone wordt encoded met %2B). |
| filteren binnen expand | /Persoon?$filter=FractieZetelPersoon/any(a:a/TotEnMet eq null)&$expand=FractieZetelPersoon($expand=FractieZetel($expand=Fractie)) |
| sorteren binnen entiteit | /Activiteit?$orderby=Nummer desc |
| sorteren binnen expand met filter | /Activiteit?$expand=Agendapunt($orderby=Nummer desc)&$filter=Nummer eq '2015A04079' |
| eerste x (10) resultaten tonen | $top=10 |
| meerdere waarden tegelijk filteren | /Activiteit?&$filter=Nummer in ('2009A00380','2015A04079') |
Dit zijn slechts enkele voorbeelden, OData v4 heeft nog een hoop andere functies. Raadpleeg de officiële OData documentatie voor alle mogelijkheden: http://www.odata.org/
Om de server niet te veel te belasten worden standaard maximaal 250 resultaten tegelijk weergegeven. Ook voor expands geldt een maximum van 250 resultaten. Bij meer dan 250 resultaten staat er aan het einde van de resultatenlijst een verwijzing naar de volgende pagina.
Een voorbeeld:
@odata.nextLink:
"https://gegevensmagazijn.tweedekamer.nl/OData/v4/2.0/Persoon?$skip=250"
Metadata niveaus
Binnen OData v4 zijn er verschillende "metadata niveaus", deze helpen bij het begrijpen van de verschillende functies (expands, download links) per entiteit. Het is aan te raden om tijdens het ontwikkelen van een koppeling gebruik te maken van de "full" metadata optie. Hieronder de mogelijkheden met daarbij voorbeelden en een omschrijving:
| Metadata niveau | Voorbeeld | Omschrijving |
|---|---|---|
| none | /Activiteit?$format=application/json;odata.metadata=none | Geeft geen metadata, dit is sneller en kan schelen in laadtijden. |
| minimal | /Activiteit?$format=application/json;odata.metadata=minimal | Heeft een minimale set aan metadata. |
| full | /Activiteit?$format=application/json;odata.metadata=full | Geeft alle expand mogelijkheden. |