SyncFeed API
Met de SyncFeed API kan je de data uit het Gegevensmagazijn synchroniseren met een eigen database. De SyncFeed API is gebaseerd op Atom 1.0 en levert data in het machineleesbare bestandsformaat XML.
Inhoud
Locatie en versie
Om synchronisatieverzoeken te maken aan de SyncFeed API gebruik je deze URL waar je parameters aan toevoegt. Het is belangrijk dat je daarvoor de meest recente versie gebruikt:
| Locatie | API-data |
|---|---|
| https://gegevensmagazijn.tweedekamer.nl/SyncFeed/2.0 | 2.0 |
Datamodel, entiteiten en attributen
Het datamodel van de SyncFeed API is gelijk aan het informatiemodel van het Gegevensmagazijn. Het informatiemodel geeft een overzicht van alle entiteitsoorten die je kan opvragen met de SyncFeed 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.
Opstellen van een verzoek
Met de SyncFeed API kan zowel alle data als een subset van de data in het Gegevensmagazijn gesynchroniseerd worden gesynchroniseerd met een eigen database. Om dit te doen stel je een verzoek op in de vorm van een URL. Een verzoek kan gericht zijn aan een van de onderstaande eindpunten:
| Eindpunt | Resultaat |
|---|---|
| https://gegevensmagazijn.tweedekamer.nl/ SyncFeed/2.0/Feed |
Eindpunt met feed van veranderingen over tijd |
| https://gegevensmagazijn.tweedekamer.nl/ SyncFeed/2.0/Entiteiten/<id> |
Eindpunt met inhoud van een enkele entiteit op basis van zijn <id> |
| https://gegevensmagazijn.tweedekamer.nl/ SyncFeed/2.0/Resources/<id> |
Eindpunt met bestand van een enkele entiteit op basis van zijn <id> |
Op het eindpunt met de feed van veranderingen over tijd kan je de onderstaande argumenten gebruiken om het verzoek verder te specificeren. Het eerste argument begin je met een ? en elk volgend argument met een &.
| Argument | Functie |
|---|---|
| category= <entiteitsoort> |
Geeft een feed met enkel veranderingen van één entiteitsoort |
| skiptoken= <aantal> |
Geeft een feed waarvan een aantal veranderingen is overgeslagen |
| content= <internal/external> |
Geeft een feed waarvan de XML van entiteiten is ingebed (internal) of niet (external) |
Een verzoek geeft een XML-bestand als resultaat met in ieder geval de onderstaande elementen. Daarnaast zijn er per entiteitsoort specifieke elementen op basis van de attributen van de entiteitsoort.
| Element | Functie |
|---|---|
<feed> |
Startpunt van de feedpagina |
<title> |
Titel van de feedpagina |
<link rel=”self”> |
URL van het huidige verzoek |
<link rel=”next”> |
URL van de volgende feedpagina wanneer een verzoek resulteert in meer dan het maximum van 250 entiteiten per feedpagina |
<link rel=”resume”> |
URL van de huidige feedpagina wanneer een verzoek door het gebruik van skiptoken= resulteert in een feedpagina zonder entiteiten |
<updated> |
Datum waarop een verzoek door het Gegevensmagazijn is beantwoord |
<author> |
Auteur van de feed |
<rights> |
Disclaimer van de feed |
<id> |
URL van het huidige verzoek |
<entry> |
Startpunt van een entiteit |
<title> |
Id van een entiteit |
<id> |
URL van een entiteit |
<author> |
Auteur van een entiteit |
<updated> |
Datum waarop een entiteit zichtbaar is geworden in de SyncFeed API |
<category> |
Entiteitsoort van een entiteit |
<link rel=”enclosure”> |
URL van een bestand behorende bij een entiteit |
<link rel=”next”> |
URL van de feedpagina met als startpunt de volgende entiteit |
<link rel=”alternate”> |
URL van de XML van een entiteit wanneer het argument content=external is gebruikt |
<content type=”application/xml”> |
XML representatie van een entiteit wanneer het argument content=internal is gebruikt |
</entry> |
Eindpunt van een entiteit |
</feed> |
Eindpunt van de feedpagina |
Binnenhalen van de data
Voordat een database kan synchroniseren, moeten eerst alle data uit het verzoek worden binnengehaald en opgeslagen. Dit werkt als volgt:
- Sla voor iedere
<entry>van het verzoek de XML-inhoud en de waarde van het<link rel="next">element op in de eigen database.- Indien een
<entry>een<link rel="enclosure">element bevat, betekent dit dat er een achterliggend bestand beschikbaar is. Dit bestand kan gedownload worden door de URL in dit element te volgen.
- Indien een
- Nadat alle beschikbare
<entry>elementen van een verzoek zijn verwerkt, dient er een nieuwe verzoek gemaakt te worden op basis van de waarde van de URL in het<link rel="next">element van de laatst verwerkte<entry>. - Herhaal stap 1 en 2 tot er geen
<entry>resultaten meer beschikbaar zijn. Wanneer dit het geval is zijn alle beschikbare data binnengehaald.
Synchroniseren van de data
Om een database te synchroniseren met de SyncFeed API moet je de API regelmatig opnieuw bevragen met behulp van de <link rel="next"> waarde van de laatst verwerkte <entry>. Het overzicht ververst dus niet automatisch.
Het is mogelijk dat een eerdere opgehaalde entiteit opnieuw voorkomt in de feed. Dit betekent dat een entiteit is geüpdatet sinds de vorige keer dat je het hebt binnengehaald. Dit kan je controleren met met het unieke identificatienummer (GUID) van het document, die is dan anders dan bij de vorige versie.
Vragen
Heb je na het lezen van deze documentatie nog vragen? Kijk eerst bij de veelgestelde vragen of neem anders contact op.