Getting Started
De ‘BRP Reisdocumenten’ Web API biedt functionaliteit om gegevens van reisdocumenten 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 Reisdocumenten’ in de proef omgeving
- Download en lees het onboardingproces
API specificatie en functionele documentatie
De ‘BRP Reisdocumenten’ Web API is gespecificeerd met behulp van de OpenAPI Specification v3.0.3.
De OAS3 specificatie van de ‘BRP Reisdocumenten’ Web API kan worden bekeken met behulp van Redoc.
De functionele documentatie van de ‘BRP Reisdocumenten’ Web API vindt je in de features overzicht.
Probeer de API in de proef omgeving
Je kunt de ‘BRP Reisdocumenten’ Web API uitproberen in de proef omgeving. De API is te bevragen op de volgende endpoint: https://proefomgeving.haalcentraal.nl/haalcentraal/api/reisdocumenten/reisdocumenten. Hiervoor heb je een apikey nodig.
De proef omgeving ontsluit reisdocumenten 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 worden op basis van een reisdocumentnummer gegevens van de bijbehorende reisdocument opgehaald
curl --request POST \
--url 'https://proefomgeving.haalcentraal.nl/haalcentraal/api/reisdocumenten/reisdocumenten' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <<APIKEY>>' \
--data '{
"type": "RaadpleegMetReisdocumentnummer",
"reisdocumentnummer": ["IVJ892799"],
"fields": [
"reisdocumentnummer",
"soort",
"houder"
]
}'
Onderstaand figuur visualiseert de configuratie van bovenstaande aanroep in Postman
Opmerking. In de proefomgeving kunnen alleen reisdocumenten van test personen die staan ingeschreven in de gemeente Rotterdam (gemeenteVanInschrijving = 0599) worden geraadpleegd.
Probeer de Proxy lokaal met Docker Desktop
Door wettelijke restricties kan de ‘BRP Reisdocumenten’ 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 Reisdocumenten’ Proxy worden gebruikt om de bewerkte gegevens te kunnen krijgen.
De ‘BRP Reisdocumenten’ Proxy is een containerized applicatie die in de omgeving van een consumer moet worden gehost. Bevragingen van de ‘BRP Reisdocumenten’ Web API moet naar de ‘BRP Reisdocumenten’ Proxy worden gestuurd, zodat deze de bevragingen kan routeren naar de GBA variant van de ‘BRP Reisdocumenten’ Web API. Responses van deze Web API worden getransformeerd naar responses conform de BRP Reisdocumenten OAS3 specificatie voordat deze naar de bevrager worden gestuurd.
Onderstaand figuur is een globale illustratie van de communicatie tussen een consumer applicatie en een Haal Centraal Web API.
De ‘BRP Reisdocumenten’ 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 Reisdocumenten’ Proxy op te starten:
docker-compose up -d
Behalve de ‘BRP Reisdocumenten’ Proxy wordt lokaal ook een mock van de GBA variant van de ‘BRP Reisdocumenten’ Web API opgestart. De mock maakt het mogelijk om lokaal zonder apikey de functionaliteit van de ‘BRP Reisdocumenten’ Web API uit te proberen.
Met behulp van het volgende curl statement worden op basis van een reisdocumentnummer gegevens van het bijbehorende reisdocument via de ‘BRP Reisdocumenten’ Proxy bij de mock opgehaald
curl --request POST \
--url 'http://localhost:5002/haalcentraal/api/reisdocumenten/reisdocumenten' \
--header 'Content-Type: application/json' \
--data '{
"type": "RaadpleegMetReisdocumentnummer",
"reisdocumentnummer": ["IVJ892799"],
"fields": [
"reisdocumentnummer",
"soort",
"houder"
]
}'
Om de Proxy en de mock containers te stoppen moet het volgende statement worden uitgevoerd:
docker-compose down
Probeer de Proxy lokaal met Kubernetes
De ‘BRP Reisdocumenten’ 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]/.k8s){:target=”_blank” rel=”noopener”} en voer het volgende statement uit om de ‘BRP Reisdocumenten’ 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
Behalve de ‘BRP Reisdocumenten’ Proxy wordt lokaal ook een mock van de GBA variant van de ‘BRP Reisdocumenten’ Web API opgestart. De mock maakt het mogelijk om lokaal zonder apikey de functionaliteit van de ‘BRP Reisdocumenten’ Web API uit te proberen.
Met behulp van het volgende curl statement worden op basis van een reisdocumentnummer gegevens van het bijbehorende reisdocument via de ‘BRP Reisdocumenten’ Proxy bij de mock opgehaald
curl --request POST \
--url 'http://localhost:5002/haalcentraal/api/reisdocumenten/reisdocumenten' \
--header 'Content-Type: application/json' \
--data '{
"type": "RaadpleegMetReisdocumentnummer",
"reisdocumentnummer": ["IVJ892799"],
"fields": [
"reisdocumentnummer",
"soort",
"houder"
]
}'
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 Reisdocumenten’ 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 Reisdocumenten’ Proxy in het docker compose bestand:
- Routes__0__DownstreamScheme. Het communicatieprotocol dat moet worden gebruikt voor het aanroepen van de BRP Reisdocumenten Web API GBA variant
- Routes__0__DownstreamHostAndPorts__0__Host. De host naam van de aan te roepen BRP Reisdocumenten Web API GBA variant
- Routes__0__DownstreamHostAndPorts__0__Port. Het port nummer van de aan te roepen BRP Reisdocumenten Web API GBA variant
De configuratie van de ‘BRP Reisdocumenten’ Proxy ziet in het docker compose bestand er dan als volgt uit:
reisdocumentproxy:
container_name: reisdocumentproxy
image: ghcr.io/brp-api/haal-centraal-reisdocument-bevragen-proxy:latest
build:
context: .
dockerfile: src/ReisdocumentProxy/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:
- "5002:5000"
networks:
- reisdocumenten-api-network
Start de ‘BRP Reisdocumenten’ Proxy met behulp van het volgende statement:
docker-compose up -d
Met behulp van het volgende curl statement worden op basis van een reisdocumentnummer gegevens van het bijbehorende reisdocument via de ‘BRP Reisdocumenten’ Proxy bij de GBA variant van de ‘BRP Reisdocumenten’ Web API in de proef omgeving opgehaald
curl --request POST \
--url 'http://localhost:5002/haalcentraal/api/reisdocumenten/reisdocumenten' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <<APIKEY>>' \
--data '{
"type": "RaadpleegMetReisdocumentnummer",
"reisdocumentnummer": ["IVJ892799"],
"fields": [
"reisdocumentnummer",
"soort",
"houder"
]
}'
Raadpleeg de Proxy configuratie documentatie voor een overzicht van de configuratie settings.