Algemeen
De FunderMaps Webservice (REST API) biedt de mogelijkheid om de FunderMaps producten te raadplegen op basis van nummeraanduiding, pandnummer of adres. Elke aanvraag, inclusief de aangevraagde product-ID, wordt opgeslagen, ongeacht of dit ID bestaat. Deze data kan later bij FunderMaps worden opgevraagd. Hierdoor is het mogelijk om gegevens en informatie op pandniveau te verkrijgen die bij het afgenomen product horen.
API Key
Een API key (ofwel auth key) is vereist om de FunderMaps producten te bevragen. Deze API key moet verkregen worden bij FunderMaps en heeft de volgende structuur:
fmsk.{32 characters}- Voorbeeld:
fmsk.<jouw-api-key>
Bevragen
De API key wordt meegegeven in de productaanvraag. Dit kan op 2 manieren:
Authenticatie via query string
Authenticatie via de query string geeft de API key mee als onderdeel van de URL (?authkey=). Deze methode kan direct in de browser worden gebruikt en is handig voor het testen van de webservice, producten of de API key.
Deze authenticatiemethode wordt niet aangeraden voor een webservice koppeling.
Voorbeeld product call:
curl 'https://ws.fundermaps.com/api/v3/product/analysis/NL.IMBAG.NUMMERAANDUIDING.0399200000000095?authkey=fmsk.<jouw-api-key>'
Resultaten in JSON-formaat
De resultaten van de API-aanvragen worden in JSON-formaat teruggegeven. Dit formaat biedt gestructureerde gegevens die eenvoudig te verwerken zijn in verschillende systemen en applicaties.
Authenticatie via header
Authenticatie via authorization header geeft de API key mee in de Authorization header van de HTTP aanvraag met de AuthKey identifier. Deze methode wordt aangeraden voor webservice koppelingen.
Authorization header gebruikt GEEN Bearer token maar een AuthKey token.
Voorbeeld product call:
curl 'https://ws.fundermaps.com/api/v3/product/analysis/NL.IMBAG.NUMMERAANDUIDING.0399200000000095' \
-H "Authorization: AuthKey fmsk.<jouw-api-key>"
HTTP-statuscodes in de API
De API retourneert de volgende HTTP-codes:
- 200 – OK. Er is data beschikbaar in JSON-formaat.
- 400 – Bad Request. De aanvraag is incorrect of mist vereiste parameters.
- 401 – Unauthorized. De API-key is ongeldig of er is geen toegang tot de resource.
- 404 – Resource Not Found. Dit betekent dat er geen data gevonden is op het opgegeven BAG-ID. Dit resulteert in een echte 404 en niet in een lege response.
- 500 – Server Error. Dit duidt op een probleem aan de kant van FunderMaps.
Daarnaast is het goed om te realiseren dat de applicatie in de cloud draait en wordt gehost door een cloudprovider met een eigen proxy/server. Hierdoor kunnen er ook andere HTTP-codes terugkomen die niet direct door FunderMaps worden gegenereerd. Het is aan te raden om HTTP-codes in brede ranges te interpreteren, zoals:
- 4xx – Client errors (bijv. fout in de aanvraag, authenticatieproblemen).
- 5xx – Server errors (bijv. interne fout, tijdelijke onbeschikbaarheid).
API-belastbaarheid en limieten
Er zijn geen harde API-limieten, anders dan op authenticatie, en die gelden alleen voor loginpogingen.
De productieomgeving van de webservice is aanzienlijk sterker dan de stagingomgeving. Staging is puur bedoeld voor het testen van logica en wijkt qua infrastructuur af van productie.
Eerdere stress-tests op de productieomgeving hebben aangetoond dat zowel de webservice als de database 100.000 aanvragen zouden moeten kunnen verwerken. Mocht er desondanks iets onverwachts gebeuren (bijv. traagheid of ingrijpen door Digital Ocean, de hosting provider), dan is het belangrijk dit te melden.
Let op: De aanvragen worden verwacht sequentieel te worden uitgevoerd. Parallelle aanvragen dienen voorkomen te worden.
Producten
De Webservice biedt twee producten: