U bent hier

API en informatiemodel veranderingen in april 2019 release

De release van aankomende april 2019 zal heel wat veranderingen met zich meebrengen. Deze pagina beschrijft de verschillen per categorie. In eerdere nieuwsartikelen was al te lezen dat om het systeem goed synchroon te houden er veranderingen in de architectuur worden doorgevoerd. Voor de afnemers veranderen het informatiemodel en de 2 API's.

Informatiemodel

Het nieuwe informatiemodel ziet er als volgt uit:

Hieronder per entiteit een omschrijving wat er wijzigt. Daarnaast verdwijnen er een aantal verbindingen omdat verslagen voortaan als een document worden beschouwd en niet meer getransformeerd worden. Vergadering en Verslag zijn hierdoor nu geïsoleerd. 

Verschillen entiteiten
Versie 1.16.2 Versie 2.0 Opmerkingen:
Activiteit Activiteit  
Actor Actor Deze bestaat nog steeds uit meerdere entiteiten, deze zijn hier niet weergegeven. (Persoon, Fractie, Commissie en de bijbehorende data. Daarnaast bevat dit blok de ActiviteitActor, DocumentActor en ZaakActor.)
Agendapunt Agendapunt  
Besluit Besluit  
Bestand   Het bestand is voortaan op te halen bij de betreffende entiteit. (Document, Persoon of Fractie)
Fractie Fractie  
Kamerstuk   Vervalt, het volgnummer / ondernummer staat voortaan bij Document.
Kamerstukdossier Kamerstukdossier  
Parlementair document Document Deze entiteit is hernoemd.
Reservering Reservering  
Stemming Stemming  
Vergadering Vergadering  
Versie Versie  
Verslag Verslag Het verslag wordt voortaan opgeslagen als document en niet meer aangepast en in een ander model opgeslagen.
Zaak Zaak  
Zaal Zaal  

OData V3 wordt vervangen door V4

Met V4 zijn er technische verbeteringen doorgevoerd, daarnaast committeert het protocol zich aan de OASIS standaard. Onderstaande links geven hierover meer informatie:

  • http://docs.oasis-open.org/odata/new-in-odata/v4.0/new-in-odata-v4.0.html
  • https://www.odata.org/
  • Versie release informatie:
    • V4, https://www.nuget.org/packages/Microsoft.OData.Core/7.5.3 - Nieuwe ondersteunde versie: hier wordt in doorontwikkeld.
    • V3, https://www.nuget.org/packages/Microsoft.Data.OData/5.8.4 - V3 artikel, bevestiging dat ontwikkelingen aan V3 stopt.

Zodra de V4 xml (atom) weer gaat ondersteunen dan zullen wij dit weer aan kunnen gaan zetten.

XML vervalt:
V4 geeft alleen json terug, de xml komt dus te vervallen met deze release. Json heeft een aantal voordelen t.o.v. xml, zo worden bijvoorbeeld de pakketjes kleiner en zijn deze sneller te verwerken.

Binnen OData v4 zijn er verschillende "metadata levels" waar in de V3 vroeger er een standaard "full" werd teruggegeven. Hieronder de mogelijkheden met daarbij voorbeelden en een omschrijving:

Metadata level 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, bij de V3 versie was dit de standaard.

Omdat het Informatiemodel gewijzigd is zal tevens het OData punt wijzigingen bevatten. Dit zit voornamelijk in de expands en een aantal kolomnamen die aangepast zijn. Het aantal expands is aanzienlijk verminderd doordat Activiteit, Document en Zaak actoren nu het RelatieType bevatten in plaats van aparte expand per type. Downloads (bestanden) worden voor Persoon, Fractie en Document nu binnen een Resource container gezet. Hier hoef je dus geen expand meer voor te doen. Veel entiteiten bevatten nu het Id naar hun bovenliggende (parent) object. Dit zorgt ervoor dat data makkelijker synchroon te houden is en je minder expands hoeft te doen. Om complexere relaties te zien (bijvoorbeeld bij zaak) dien je nog wel de expand logica toe te passen.

Andere verschillen tussen V3 en V4:
In V3 was het mogelijk om een expand te doen met een "/". In V4 dien je de expands te nesten. De inlinecount functie is vervangen door een count.

Functie V3 V4
expand $expand=Besluit/Agendapunt/Activiteit $expand=Besluit($expand=Agendapunt($expand=Activiteit))
entiteiten tellen $inlinecount=allpages $count=true
pagineren $skiptoken=guid'2afbdad1-9e6c-47a3-b74a-0135eca21a03' $skip=250
filteren op datum $filter=Datum gt datetime’2017-01-01T00:00:00’ $filter=Datum gt 2017-01-01T00:00:00Z
filteren binnen expand /Persoon?$filter=Fractielid/any(aa: aa/TotEnMet eq null)&$expand=Fractielid/Fractie /Persoon?$filter=FractieZetelPersoon/any(a:a/TotEnMet eq null)&$expand=FractieZetelPersoon($expand=FractieZetel($expand=Fractie))

Hieronder vind je de nieuwe expands:

OData V4 expands in 2.0 versie
Entiteit versie 2.0 Expand naar.... (En vice versa) Opmerkingen:
Activiteit ActiviteitActor  
Activiteit Agendapunt  
Activiteit Document  
Activiteit Reservering  
Activiteit VervangenDoor  
Activiteit VervangenVanuit  
Activiteit VoorgezetIn  
Activiteit VoorgezetVanuit  
Activiteit Voortouwcommissie  
Activiteit Zaak  
Agendapunt Activiteit .
Agendapunt Besluit  
Agendapunt Document  
Agendapunt Zaak  
Besluit Agendapunt  
Besluit Stemming  
Besluit Zaak  
Commissie Activiteit  
Commissie ActiviteitActor  
Commissie CommissieContactinformatie  
Commissie DocumentActor  
Commissie ZaakActor  
Commissie CommissieZetel  
CommissieZetel CommissieZetelVastPersoon  
CommissieZetel CommissieZetelVastVacature  
CommissieZetel CommissieZetelVervangerPersoon  
CommissieZetel CommissieZetelVervangerVacature  
Document Activiteit  
Document DocumentActor  
Document Agendapunt  
Document BijlageDocument  
Document BronDocument  
Document HuidigeDocumentVersie .
Document Kamerstukdossier  
Document DocumentVersie  
Document VervangenDoor Komt te vervallen, komt niet voor in het bronsysteem.
Document VervangenVanuit Komt te vervallen, komt niet voor in het bronsysteem.
Document Zaak  
DocumentVersie Document  
Fractie FractieAanvullendGegeven  
Fractie ActiviteitActor  
Fractie CommissieZetelVastVacature Een zetel in een commissie kan op fractie zijn.
Fractie CommissieZetelVervangerVacature Een zetel in een commissie kan op fractie zijn.
Fractie DocumentActor  
Fractie Stemming  
Fractie ZaakActor  
Fractie FractieZetel  
FractieZetel FractieZetelPersoon Voorheen was dit "FractieLid".
FractieZetel FractieZetelVacature Voorheen was dit "FractieLid".
Kamerstukdossier Document  
Kamerstukdossier Zaak  
Persoon ActiviteitActor  
Persoon CommissieZetelVastPersoon  
Persoon CommissieZetelVervangerPersoon  
Persoon PersoonContactinformatie  
Persoon DocumentActor  
Persoon FractieZetelPersoon  
Persoon PersoonGeschenk  
Persoon PersoonLoopbaan  
Persoon PersoonNevenfunctie  
Persoon PersoonOnderwijs  
Persoon PersoonReis  
Persoon Stemming  
Persoon ZaakActor  
PersoonNevenfunctie Persoon  
PersoonNevenfunctie PersoonNevenfunctieInkomsten  
Reservering Activiteit  
Reservering Zaal  
Vergadering Verslag  
Zaak Activiteit  
Zaak ZaakActor  
Zaak Agendapunt  
Zaak Besluit  
Zaak Document  
Zaak GerelateerdNaar  
Zaak GerelateerdVanuit  
Zaak HoofdOverig Komt te vervallen, komt niet voor in het bronsysteem.
Zaak GerelateerdOverig Komt te vervallen, komt niet voor in het bronsysteem.
Zaak Kamerstukdossier  
Zaak VervangenDoor  
Zaak VervangenVanuit  
Zaal Reservering  

REST wordt SyncFeed (Atom 1.0)

De naamgeving van de REST in de vorige versie gaf een hoop onduidelijkheden. We gaan deze versimpelen en hernoemen naar SyncFeed. Deze API is bedoeld om systemen synchroon te houden: De service implementeert protocollen die paginering en update-detectie mogelijk maken zodat batchprocessen robuust en efficiënt informatie kunnen uitlezen, opslaan en bijwerken. Let wel: Dit kan tevens met het OData punt. Functies als het zoeken door de attributen dient te gebeuren in de OData API, XQuery ondersteuning vervalt. Wel is er nog steeds te filteren per rootentiteit. De service voldoet aan de "Atom 1.0 feed" definitie, tevens beschreven op: https://validator.w3.org/feed/docs/atom.html .

Er zijn grote verschillen qua rootentiteiten. Sommigen vervallen maar er komen er voornamelijk extra bij. In het OData punt is dit verschil een stuk minder. De reden dat dit zoveel scheelt is dat de XML niet meer "genest" wordt. Zo zaten bijvoorbeeld deze entiteiten allen onder /activiteit: /activiteit/agendapunt/besluit/stemming. Nu hebben deze entiteiten allen een eigen root. Dit maakt het synchroon houden van de data een stuk gemakkelijker. 

De url wordt aangepast en "/REST" vervalt. Een kort overzicht:

  • /SyncFeed/Feed = Volledige feed met alle entiteiten
    • ?category=activiteit (simpel filter op entiteit soort)
  • /SyncFeed/Resources/<guid> = resource binary ophalen
  • /SyncFeed/Entiteiten/<guid> = manier om een enkele entiteit op basis van Guid op te halen.

Paginering: Piket wordt skiptoken
De “piket” optie is hernoemd naar “skiptoken”. Daarnaast is het skiptoken een integer (bijvoorbeeld &skiptoken=721) geworden ipv een gehaste string (bijvoorbeeld piket=GaboAAAAAAA%3D).De <link rel="self" /> en <link rel="next" /> staan voortaan bovenaan het resultaat, conform Atom 1.0 standaard.

De functie "content=internal" is de standaard, "content=external" geeft de attributen niet terug. Een voorbeeld die standaard terugkomt:

<feed xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.w3.org/2005/Atom">
   <title>Gegevensmagazijn SyncFeed (category: document)</title>
   <link rel="self" href=url/SyncFeed/feed?category=document" />
   <link rel="next" href="https://opendata.tweedekamer.nl/url/SyncFeed/Feed?category=document&skiptoken=103504" />
   <updated>2019-01-03T16:50:38.9126307+01:00</updated>
   <author>
      <name>Tweede Kamer der Staten-Generaal</name>
      <uri>https://opendata.tweedekamer.nl</uri>
   </author>
   <rights>
Het is gebruikers toegestaan de informatie en gegevens van deze internetsite met bronvermelding over te nemen voor eigen gebruik door deze te kopiëren, uit te printen of op te slaan. Het is niet toegestaan de verstrekte informatie en gegevens evenals de ontwerpen en symbolen van de Tweede Kamer der Staten-Generaal te gebruiken voor doeleinden waarvoor het ongepast is, of in gevallen waarin de kans bestaat dat er misverstanden over de oorsprong kunnen ontstaan, dan wel in gevallen waarin men doet voorkomen dat het door de Tweede Kamer der Staten-Generaal is geautoriseerd.
   </rights>
   <id>url//SyncFeed/feed?category=document</id>
   <entry>
   <title>4f89565b-7c53-4d4f-b729-eda6bf893b01</title>
   <id>
      url/SyncFeed/Entiteiten/4f89565b-7c53-4d4f-b729-eda6bf893b01
   </id>
   <author>
      <name>Tweede Kamer der Staten-Generaal</name>
   </author>
   <updated>2019-01-03T14:17:33Z</updated>
   <category term="document" />
   <link rel="enclosure" href="https://opendata.tweedekamer.nl/SyncFeed/Resources/4f89565b-7c53-4d4f-b729-eda6bf893b01" />
   <content>
      <document xmlns:tk="http://www.tweedekamer.nl/xsd/tkData/v1-0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.tweedekamer.nl/xsd/tkData/v1-0" id="4f89565b-7c53-4d4f-b729-eda6bf893b01" tk:bijgewerkt="2008-11-04T15:31:27.643" tk:verwijderd="false" tk:contentType="application/msword" tk:contentLength="25600">
            <<attributen van document>>
         </document>
      </content>
   </entry>

Verschillen rootentiteiten
Versie 1.16.2 Versie 2.0 Opmerkingen:
bestand   In de nieuwe versie zit het bestand aan de entiteit vast en is dit geen aparte entiteit meer.
activiteit activiteit  
  activiteitActor Zat genest onder activiteit als: 
/afgemeld, /bewindspersoon, /deelnemer, /initiatiefnemer, /interpellant, /volgcommissie en /voortouwcommissie.
Voortaan is de relatie te zien in de kolom "relatie".
  agendapunt Zat genest onder activiteit.
  besluit Zat genest onder activiteit.
commissie commissie  
  commissieContactinformatie Zat genest onder commissie.
  commissieZetel Zat genest onder commissie.
  commissieZetelVastPersoon Zat genest onder commissie.
  commissieZetelVastVacature Zat genest onder commissie.
  commissieZetelVervangerPersoon Zat genest onder commissie.
  commissieZetelVervangerVacature Zat genest onder commissie.
parlementairDocument document Let op: Deze is hernoemd.
  documentActor Zat genest onder document als:
/ondertekenaar, /medeOndertekenaar, /namens, /medeNamens, /afzender, /medeAfzender en /geadresseerde. 
Voortaan is de relatie te zien in de kolom "relatie".
  documentVersie Zat genest onder document.
fractie fractie  
  fractieAanvullendGegeven Zat genest onder fractie.
  fractieZetel Zat genest onder fractie.
  fractieZetelPersoon Zat genest onder fractie.
  fractieZetelVacature Zat genest onder fractie.
kamerstukdossier kamerstukdossier  
persoon persoon  
  persoonContactinformatie Zat genest onder persoon.
  persoonGeschenk Zat genest onder persoon.
  persoonLoopbaan Zat genest onder persoon.
  persoonNevenfunctie Zat genest onder persoon.
  persoonNevenfunctieInkomsten Zat genest onder persoon.
  persoonOnderwijs Zat genest onder persoon.
  persoonReis Zat genest onder persoon.
reservering reservering  
  stemming Zat genest onder activiteit.
vergadering vergadering  
verslag verslag  
zaak zaak  
  zaakActor Zat genest onder zaak als: /gerichtAan, /rapporteur, /indiener, /medeindiener, /volgcommissie en /voortouwcommissie.
Voortaan is de relatie te zien in de kolom "relatie".
  zaal Zat genest onder reservering.