Haal Centraal / BRP Reisdocumenten / Getting Started

Getting Started

The ‘Reisdocumenten bevragen’ Web API offers functionality for querying travel document data.

View the API specification and functional documentation
Try the API in the pilot environment
Try the Proxy locally with Docker Desktop
Try the Proxy locally with Kubernetes
Route Proxy calls to the GBA variant of the Web API in the pilot environment
Download and read the onboarding process

API specification and functional documentation

The ‘Reisdocumenten bevragen’ Web API is specified using the OpenAPI Specification v3.0.3.

The OAS3 specification of the ‘Reisdocumenten bevragen’ Web API can be viewed with Redoc.

The functional documentation of the ‘Reisdocumenten bevragen’ Web API can be found in the features overview.

Trying the API in the pilot environment

You can try out the ‘Reisdocumenten bevragen’ Web API in the pilot environment. The API can be queried at the following endpoint: https://proefomgeving.haalcentraal.nl/haalcentraal/api/reisdocumenten/reisdocumenten. For this you need an API key.

The pilot environment exposes travel documents that occur in the Basisregistratie Personen test dataset.

Request an API key from the product owner, or use the API key issued at the API Labs.

With the following curl statement, data of the corresponding travel document is retrieved on the basis of a travel document number:

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"
  ]
}'

The figure below visualizes the configuration of the above call in Postman.

Note. In the pilot environment, only travel documents of test persons registered in the municipality of Rotterdam (gemeenteVanInschrijving = 0599) can be consulted.

Terms used in this screenshot

Reisdocumenten test	Travel documents test (Postman collection name)
Raadpleeg met reisdocumentnummer	Consult by travel document number (request name)
reisdocumentnummer	travel document number
gemeenteVanInschrijving	municipality of registration
soort	type (of travel document)
houder	holder (person to whom the document belongs)

Trying the Proxy locally with Docker Desktop

Because of statutory restrictions, the ‘Reisdocumenten bevragen’ Web API cannot carry out certain operations. Work is currently under way on the Experimentbesluit Dataminimalisatie to remove these restrictions. Until the experiment decision is in force, the ‘Reisdocumenten bevragen’ Proxy must be used to obtain the processed data.

The ‘Reisdocumenten bevragen’ Proxy is a containerized application that must be hosted in the environment of a consumer. Queries of the ‘Reisdocumenten bevragen’ Web API must be sent to the ‘Reisdocumenten bevragen’ Proxy, so that it can route the queries to the GBA variant of the ‘Reisdocumenten bevragen’ Web API. Responses from this Web API are transformed into responses conforming to the Reisdocumenten bevragen OAS3 specification before they are sent to the party making the query.

The figure below is a general illustration of the communication between a consumer application and a Haal Centraal Web API.

Haal Centraal communication, general overview

The ‘Reisdocumenten bevragen’ Proxy can be tried out locally using Docker Desktop. For this:

Docker Desktop must be installed on a Windows or Mac PC
the docker compose file must be downloaded on the same Windows or Mac PC

Open a command prompt in the folder with the downloaded docker compose file and run the following statement to start the ‘Reisdocumenten bevragen’ Proxy:

docker-compose up -d

Besides the ‘Reisdocumenten bevragen’ Proxy, a mock of the GBA variant of the ‘Reisdocumenten bevragen’ Web API is also started locally. The mock makes it possible to try out the functionality of the ‘Reisdocumenten bevragen’ Web API locally without an API key.

With the following curl statement, data of the corresponding travel document is retrieved from the mock through the ‘Reisdocumenten bevragen’ Proxy, on the basis of a travel document number:

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"
  ]
}'

To stop the Proxy and the mock containers, the following statement must be run:

docker-compose down

Trying the Proxy locally with Kubernetes

The ‘Reisdocumenten bevragen’ Proxy can also be tried out locally using Kubernetes. For this:

Docker Desktop must be installed on a Windows or Mac PC
Kubernetes support must be switched on in Docker Desktop, in the Settings/Kubernetes configuration screen
the Kubernetes manifest files must be downloaded on the same Windows or Mac PC

Open a command prompt in the folder with the downloaded Kubernetes manifest files and run the following statement to start the ‘Reisdocumenten bevragen’ Proxy:

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

To stop the Proxy and the mock containers, the following statement must be run:

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

Routing Proxy calls to the GBA variant of the Web API in the pilot environment

For this, environment variables must be added to the ‘Reisdocumenten bevragen’ Proxy in the docker compose file.

First stop the proxy container with the following statement:

docker-compose down

Add the following environment variables to the configuration of the ‘Reisdocumenten bevragen’ Proxy in the docker compose file:

Routes__0__DownstreamScheme. The communication protocol to be used for calling the Reisdocumenten bevragen Web API GBA variant
Routes__0__DownstreamHostAndPorts__0__Host. The host name of the Reisdocumenten bevragen Web API GBA variant to be called
Routes__0__DownstreamHostAndPorts__0__Port. The port number of the Reisdocumenten bevragen Web API GBA variant to be called

The configuration of the ‘Reisdocumenten bevragen’ Proxy in the docker compose file then looks like this:

  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 the ‘Reisdocumenten bevragen’ Proxy with the following statement:

docker-compose up -d

With the following curl statement, data of the corresponding travel document is retrieved through the ‘Reisdocumenten bevragen’ Proxy from the GBA variant of the ‘Reisdocumenten bevragen’ Web API in the pilot environment, on the basis of a travel document number:

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"
  ]
}'

See the Proxy configuration documentation for an overview of the configuration settings.