Haal Centraal Product Vision

Objective

The objective of the Haal Centraal program is to outsource the provision of base data to consumers within municipalities to national registries (RvIG, Kadaster, KVK). This should lead to a substantial reduction in local copies at municipalities.

For every activity carried out on a local copy, Haal Centraal wants to offer an alternative in the form of an API from a national registry. We are starting with REST APIs for searching and consulting base data. Specifically for WOZ and leasehold, our roadmap also includes publish-subscribe APIs for querying domain events from an event store, and we are investigating the combined querying of base registries for analyses supporting enforcement and fraud prevention.

Added value for municipalities

• faster and cheaper connection through the best possible DX
• cheaper management through design for evolvability and extensibility
• lower investments (no local copy/data warehouse)
• lower management costs (no management of local copies)
• higher ROI: reuse of the national registry API by all municipal task applications
• better technology-business alignment (a national registry implements a change faster than 355 individual municipalities)
• creates room to focus on the business needs of consumers (rather than on the reliability and currency of local copies)
• maximum compliance in the municipal software market (a connection at municipality x is 100% reusable at municipality y)

Added value for suppliers

• in line with what municipalities want, suppliers can focus on delivering added value for citizens, businesses, and staff, and on their core domain, rather than on plumbing concerns in supporting domains such as the use of base data.

Context

Haal Centraal is a G5 initiative (Amsterdam, Rotterdam, The Hague, Utrecht, and Eindhoven). The concept was tested in the BRK pilot run by the municipality of The Hague with Kadaster, on the basis of the RSGB query standard (the predecessor of BRP Bevragen and BRK Bevragen). The business case is based on empirical figures from the municipality of The Hague and on the software development carried out during the pilot.

Product vision

Business driven

Resource definition and functionality based on the business need reflecting the greatest common information requirement of all consumers within municipalities in the Netherlands.

Not to be confused with model-driven development (MDD), where the definition is based on the provider's perspective. Haal Centraal APIs can usually be traced back to an underlying information model (so that the feasibility and semantics of the API are safeguarded), but are as loosely coupled as possible. Implementation bleed and tight coupling with provider implementation details are avoided.

Consumer first

Place the benefits with the consumer (= the consumer within the municipality) wherever possible, because of the leverage effect: the complexity sits with the provider (build and manage once), while the benefits in cost and lead time sit with the consumer ((number of consumers within the municipality x 351) x build and manage)

Developer first

Focus on usability for the developer: the OAS spec has been tested for code generation (Java, .NET, and Python, the most widely used in the municipal market), design decisions have been assessed for their effect on the code, maximum consistency with other Haal Centraal APIs, and behavior-driven development (BDD) scenarios in Gherkin to describe the behavior of the API.

Contract first

…and not code first. The API is agnostic, free of implementation details of the provider system, and not sensitive to changes in system logic at the provider.

Agnostic

= without knowledge of the consumer. The API must be usable by all (in theory 200 different) municipal processes and by products of other government parties that need base data.

Evolvable

Haal Centraal APIs are extensible and evolvable. The aim is to introduce no breaking changes, or as few as possible.

Implemented

APIs are implemented by a national registry (RvIG, Kadaster, KVK, etc.)

Non-functionals:

• extremely fast
• scalable
• reliable
• resilient
• laid down in an SLA and a Dossier of Agreements and Procedures

Scope

Design based on an inventory of the information needs of consumers within municipalities. The scope is limited to the base data available to the national registry.

Principles

• All code, documents, and specifications produced in this process are published as open source under the EUPL license;
• For the specification of APIs, OpenAPI Specification v3.x is used. This has been placed on the “comply or explain” list by Forum Standaardisatie (the Standardization Forum);
• Wherever possible, the API strategy and the REST API Design Rules are applied.

Realization

We work in an agile way as much as possible. The activities below are part of an iterative process.

• we turn every municipal information need into a user story.
• user stories are mapped onto a Goals Canvas, which we use to specify the basic functions and endpoints of the API.
• For the most common stories we create a definition in OpenAPI (and, if necessary, features for the provider).
• a designer from VNG Realisatie defines the API in OpenAPI together with the PO, a domain expert and developer from the national registry, a tester, and a developer from VNG Realisatie.
• every definition is assessed for DX, including code generation by a developer from VNG Realisatie, our own customer zero.
• the (draft) definition is implemented by a national party
• the definition is adjusted on the basis of questions and comments from the provider and other stakeholders, for example following a field lab
• testing is carried out primarily by the national registry, but also by at least 1 municipality.
• (a version of) the API is put into production and managed by the national registry
• onboarding through the national registry, documentation through the Haal Centraal repository on GitHub.