Getting Started

De ‘BRP Bewoning’ Web API biedt functionaliteit om de bewoning van een adresseerbaar object te bevragen.

Bekijk de API specificatie en functionele documentatie
Probeer de API in de proef omgeving
Probeer de Proxy lokaal met Docker Desktop
Probeer de Proxy lokaal met Kubernetes
Routeer Proxy aanroepen naar de GBA variant van de ‘BRP Bewoning’ in de proef omgeving
Download en lees het onboardingproces

API specificatie en functionele documentatie

De ‘BRP Bewoning’ Web API is gespecificeerd met behulp van de OpenAPI Specification v3.0.3.

Je kunt de OAS3 specificatie van de ‘BRP Bewoning’ Web API bekijken met behulp van Redoc.

De functionele documentatie van de ‘BRP Bewoning’ Web API vind je in de features overzicht.

Probeer de API in de proef omgeving

Je kunt de ‘BRP Bewoning’ Web API uitproberen in de proef omgeving. Bevraag de API op het volgende endpoint: https://proefomgeving.haalcentraal.nl/haalcentraal/api/bewoning/bewoningen. Hiervoor heb je een apikey nodig.

De proef omgeving ontsluit de bewoning van adresseerbaar objecten die voorkomen in de Testdataset Basisregistratie Personen

Vraag een apikey aan bij de product owner of gebruik de apikey die is uitgereikt op de API Labs.

Met behulp van het volgende curl statement wordt op basis van een adresseerbaar object identificatie en peildatum de bewoning van het adresseerbaar object op de peildatum opgehaald:

curl --request POST \
--url 'https://proefomgeving.haalcentraal.nl/haalcentraal/api/bewoning/bewoningen' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <<APIKEY>>' \
--data '{
  "type": "BewoningMetPeildatum",
  "adresseerbaarObjectIdentificatie": "0599010000208579",
  "peildatum": "2015-08-08"
}'

Onderstaand figuur visualiseert de configuratie van bovenstaande aanroep in Postman.

Opmerking. In de proefomgeving kan alleen de bewoning van adresseerbaar objecten in de gemeente Rotterdam worden geraadpleegd.

Raadpleeg de bewoning van adresseerbaar op peildatum

Probeer de Proxy lokaal met Docker Desktop

Door wettelijke restricties kan de ‘BRP Bewoning’ Web API bepaalde bewerkingen niet uitvoeren. Er wordt op dit moment gewerkt aan het Experimentbesluit Dataminimalisatie om deze restricties weg te halen. Totdat het experimentbesluit van kracht is moet de ‘BRP Bewoning’ Proxy worden gebruikt om de bewerkte gegevens te kunnen krijgen.

De ‘BRP Bewoning’ Proxy is een containerized applicatie die in de omgeving van een consumer moet worden gehost. Bevragingen van de ‘BRP Bewoning’ Web API moet naar de ‘BRP Bewoning’ Proxy worden gestuurd, zodat deze de bevragingen kan routeren naar de GBA variant van de ‘BRP Bewoning’ Web API. Responses van deze Web API worden getransformeerd naar responses conform de BRP Bewoning OAS3 specificatie voordat deze naar de bevrager worden gestuurd.

Onderstaand figuur is een globale illustratie van de communicatie tussen een consumer applicatie en een BRP Web API.

Haal Centraal Communicatie Globaal Overview

De ‘BRP Bewoning’ Proxy kan lokaal worden uitgeprobeerd met behulp van Docker Desktop. Hiervoor moet:

Docker Desktop op een Windows of Mac PC worden geïnstalleerd
op dezelfde Windows of Mac PC het docker compose bestand worden gedownload

Start een command prompt in de map met het gedownloade docker compose bestand en voer het volgende statement uit om de ‘BRP Bewoning’ Proxy op te starten:


docker-compose up -d

Behalve de ‘BRP Bewoning’ Proxy wordt lokaal ook een mock van de GBA variant van de ‘BRP Bewoning’ Web API opgestart. De mock maakt het mogelijk om lokaal zonder apikey de functionaliteit van de ‘BRP Bewoning’ Web API uit te proberen.

Met behulp van het volgende curl statement wordt op basis van een adresseerbaar object identificatie en peildatum de bewoning van het adresseerbaar object op de peildatum via de ‘BRP Bewoning’ Proxy bij de mock opgehaald:

curl --request POST \
--url 'http://localhost:5003/haalcentraal/api/bewoning/bewoningen' \
--header 'Content-Type: application/json' \
--data '{
  "type": "BewoningMetPeildatum",
  "adresseerbaarObjectIdentificatie": "0599010000208579",
  "peildatum": "2015-08-08"
}'

Om de Proxy en de mock containers te stoppen moet de volgende statement worden uitgevoerd:


docker-compose down

Probeer de Proxy lokaal met Kubernetes

De ‘BRP Bewoning’ Proxy kan lokaal ook worden uitgeprobeerd met behulp van Kubernetes. Hiervoor moet:

Docker Desktop op een Windows of Mac PC worden geïnstalleerd
in Docker Desktop de Kubernetes ondersteuning worden aangezet in de Settings/Kubernetes configuratie scherm
op dezelfde Windows of Mac PC de Kubernetes manifest bestanden worden gedownload

Start een command prompt in de map met de gedownloade [Kubernetes manifest bestanden]https://github.com/BRP-API/Haal-Centraal-BRP-bewoning/blob/master/.k8s){:target=”_blank” rel=”noopener”} en voer het volgende statement uit om de ‘BRP Bewoning’ Proxy op te starten:

kubectl apply -f .k8s/proxy-deployment.yaml \
              -f .k8s/proxy-service.yaml \
              -f .k8s/mock-deployment.yaml \
              -f .k8s/mock-service.yaml 

curl --request POST \
--url 'http://localhost:5003/haalcentraal/api/bewoning/bewoningen' \
--header 'Content-Type: application/json' \
--data '{
  "type": "BewoningMetPeildatum",
  "adresseerbaarObjectIdentificatie": "0599010000208579",
  "peildatum": "2015-08-08"
}'

Om de Proxy en de mock containers te stoppen moet het volgende statement worden uitgevoerd:

kubectl delete -f .k8s/proxy-deployment.yaml \
                -f .k8s/proxy-service.yaml \
                -f .k8s/mock-deployment.yaml \
                -f .k8s/mock-service.yaml 

Routeer Proxy aanroepen naar de GBA variant van de Web API in de proef omgeving

Hiervoor moeten environment variabelen worden toegevoegd aan de ‘BRP Bewoning’ Proxy in het docker compose bestand.

Stop eerst de proxy container met behulp van het volgende statement:


docker-compose down

Voeg de volgende environment variabelen toe aan de configuratie van de ‘BRP Bewoning’ Proxy in het docker compose bestand:

Routes__0__DownstreamScheme. Het communicatieprotocol dat moet worden gebruikt voor het aanroepen van de BRP Bewoning Web API GBA variant
Routes__0__DownstreamHostAndPorts__0__Host. De host naam van de aan te roepen BRP Bewoning Web API GBA variant
Routes__0__DownstreamHostAndPorts__0__Port. Het port nummer van de aan te roepen BRP Bewoning Web API GBA variant

De configuratie van de ‘BRP Bewoning’ Proxy ziet in het docker compose bestand er dan als volgt uit:

  bewoningproxy:
    container_name: bewoningproxy
    image: ghcr.io/brp-api/haal-centraal-bewoning-bevragen-proxy:latest
    build:
      context: .
      dockerfile: src/BewoningProxy/Dockerfile
    environment:
      - ASPNETCORE_ENVIRONMENT=Release
      - ASPNETCORE_URLS=http://+:5000
      - Routes__0__DownstreamScheme=https
      - Routes__0__DownstreamHostAndPorts__0__Host=proefomgeving-gba.haalcentraal.nl
      - Routes__0__DownstreamHostAndPorts__0__Port=443
    ports:
      - "5003:5000"
    networks:
      - bewoningen-api-network

Start de ‘BRP Bewoning’ Proxy met behulp van het volgende statement:


docker-compose up -d

Met behulp van het volgende curl statement wordt op basis van een adresseerbaar object identificatie en peildatum de bewoning van het adresseerbaar object op peildatum via de ‘BRP Bewoning’ Proxy bij de GBA variant van de ‘BRP Bewoning’ Web API in de proef omgeving opgehaald:

curl --request POST \
--url 'http://localhost:5003/haalcentraal/api/bewoning/bewoningen' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <<APIKEY>>' \
--data '{
  "type": "BewoningMetPeildatum",
  "adresseerbaarObjectIdentificatie": "0599010000208579",
  "peildatum": "2015-08-08"
}'

Raadpleeg de Proxy configuratie documentatie voor een overzicht van de configuratie settings.