Gebruik API's

Het RIVM biedt verschillende soorten API's aan via het developer portal. Op deze pagina wordt een algemene beschrijving gegeven van het gebruik van een API. Meer informatie over het gebruik van een specifieke API is beschikbaar op de informatiepagina van de betreffende API.

REST

De meeste API's die aangeboden worden via het developer portal zijn gebaseerd op het Representation State Transfer (REST) principe, gebruik makend van het communicatie protocol HTTP. Hiermee kunnen data entiteiten benaderd worden via HTTP requests naar specifieke URL's. Een URL verwijst naar een verzameling entiteiten, of een specifieke entiteit uit die verzameling, en de HTTP method geeft de operatie aan die uitgevoerd moet worden, bijv. data ophalen of bijwerken. Data wordt aangeleverd of opgehaald via de HTTP request of response body; meestal wordt het JSON data formaat gebruikt.

Als voorbeeld nemen we een fictieve API voor waterkwaliteitmetingen die beschikbaar is op de base URL https://api.rivm.nl/waterkwaliteit/v1. Een lijst van metingen in het systeem zou opgehaald kunnen worden door een GET request te doen naar de URL https://api.rivm.nl/waterkwaliteit/v1/metingen. Een nieuwe meting kan toegevoegd worden door een POST request met de data van de meting te doen naar dezelfde URL. Als de meting succesvol opgeslagen is, zal de API antwoorden met een ID voor de nieuwe meting, bijv. 12345. De gegevens van deze specifieke meting kunnen dan opgehaald worden door een GET request te doen naar https://api.rivm.nl/waterkwaliteit/v1/metingen/12345. De meting kan bijgewerkt worden door een PUT request met nieuwe gegevens te doen naar dezelfde URL en de meting kan verwijderd worden door een DELETE request te doen. Verdere informatie kan ook gespecificeerd worden met request parameters. Bijv. alle metingen in Amsterdam kunnen opgehaald worden met een GET request naar https://api.rivm.nl/waterkwaliteit/v1/metingen?city=Amsterdam. Meer informatie over REST is op diverse plekken op het internet te vinden, zoek op RESTFUL API. Wij sluiten aan bij de standaarden binnen het Rijk, in de REST API Design Rules worden de architectuur principes van REST uitgebreid beschreven inclusief voorbeelden.

JSON

De informatie die wordt uitgewisseld via een REST API van het RIVM gebruikt doorgaans het JavaScript Object Notation (JSON) dataformaat. Dit beschrijft entiteiten (objecten) in een human-readable tekstformaat als een set van key-value pairs. Ieder key-value pair geeft een bepaalde eigenschap van de entiteit weer. Een key is een string; een value kan een nummer, string, boolean, object of lijst (array) zijn. Een key en een value worden gescheiden met een : (dubbele punt). De key-value pairs worden gescheiden met komma's en de gehele set begint en eindigt met resp. een { en een } (curly braces). Elementen in een lijst (array) worden ook gescheiden met komma's, maar de gehele lijst begint en eindigt met resp. een [ en een ] (brackets).

Ter verduidelijking een voorbeeld van de fictieve waterkwaliteit API. De informatie van een meting zou er als volgt uit kunnen zien:

{
  "id": 12345,
  "city": "Utrecht",
  "bodyOfWater": "Vecht",
  "timestamp": "2025-10-23T14:55:43.712Z",
  "quality": 7.2
}

Ook over JSON is op diverse plekken op het internet meer informatie te vinden, bijv. bij W3Schools.

Dit is slechts een algemene beschrijving hoe met JSON data een REST API aangeroepen kan worden. Iedere API geeft hier zijn eigen invulling aan. Daarom is voor iedere API een zgn. OpenAPI Specification (ook wel bekend als "Swagger") beschikbaar. Deze kan ingezien en gedownload worden via de knop Opvragen specificatie op de documentatiepagina van de API. De specificatie toont een lijst met URL's en de HTTP methods waarmee ze aangeroepen kunnen worden, parameters en JSON schema's voor deze aanroepen, en welke responses verwacht kunnen worden op de aanroepen. D.m.v. de Try it out knoppen kan een request naar een endpoint uitgeprobeerd worden. Hiervoor moeten meestal wel eerst de authenticatiegegevens opgegeven worden met de Authorize knop bovenaan de pagina.

Authenticatie

Om misbruik en overbelasting van de API's te voorkomen is authenticatie vereist bij het aanroepen van een API. Een systeem authenticeert zich bij een API door twee gegevens mee te sturen: een application ID en een application key. Deze moeten bij ieder request meegestuurd worden in twee HTTP headers met de namen app_id en app_key (respectievelijk).

Om deze credentials te verkrijgen, moet de applicatie die de API gaat gebruiken geregistreerd worden in het developer portal. Afhankelijk van hoe de API beheerd wordt kan dit zelf gedaan worden via de knop Aanvragen authenticatie op de API informatie pagina (of evt. via de optie Applicaties - Maak nieuwe applicatie), of moet dit gedaan worden door de beheerder van de API. Een applicatie kan alleen aangemaakt worden als je geregistreerd en ingelogd bent bij het developer portal.

Om overbelasting te voorkomen gelden per applicatie beperkingen op het aantal requests dat uitgevoerd kan worden in een bepaalde periode. Als deze limieten overschreden worden, zal toegang tot de API voor deze applicatie geblokkeerd worden. Als de limieten bij legitiem gebruik overschreden worden, kunnnen deze in overleg met de beheerder van de API verhoogd worden.

Het is in principe de bedoeling om ieder systeem dat gebruik gaat maken van een API apart te registreren, zodat ieder systeem een eigen set credentials en een eigen request limiet krijgt. In overleg met de beheerder van de API kan hier eventueel van afgeweken worden.

Sommige API's hebben meer beveiligingsmaatregelen dan alleen een application ID en key. De beheerder van de API kan je hierover informeren.