The hbz library service centre (Hochschulbibliothekszentrum des Landes Nordrhein-Westfalen) is a service and development agency for library and information systems. We are a federal state authority under the Ministry of Culture and Science of the German state of North Rhine-Westphalia (NRW). We build software to create, transform and publish bibliographic data. We’re increasingly creating our systems as open source software on GitHub: https://github.com/hbz

The source for this document is maintained at https://github.com/hbz/hbz.github.com | Moved, previously on this page: Lobid-specific content

Common architecture

At hbz, we’re aiming to establish a common macro architecture to enable interoperability of data and application modules developed by different groups. The main idea of that macro architecture is to provide independently deployable, self-contained modules that communicate over HTTP.

Macro architecture

The goal of the macro architecture is to provide a level of integration for heterogenous software components, written in different languages and using different technologies. Not all current components conform to the architecture, and not all are open source. For an overview, see the following diagram.

Data module specification

Data modules provide a unified HTTP API to integrate into the hbz macro architecture:

Prefix

Data modules use a URL path prefix corresponding to their data set. They provide module documentation at the prefix root. For example, the organisations data set uses the organisations/ path prefix, with routes like organisations/search?q=Köln, documented at organisations/. This allows us to use multiple modules under a single domain.

Get

Data modules support GET requests for direct access to an entity using an ID path segment: organisations/DE-605. This provides URLs for every entity in our data modules.

Result

Data modules return application/json; charset=utf-8. All entities in a single data module have the same format (type, schema). This allows API users to query what they get. For example, we can look at organisations/DE-2297 to create a query like q=location.address.addressLocality:Berlin. This makes the supported queries discoverable.

Query

Data modules support GET requests with a q query parameter that can be used for simple full text queries: q=Köln, and for querying specific fields: q=name:Landesarchiv+Berlin. Fields can be nested: q=location.address.postalCode:50667. This provides a generic query mechanism with full access to the specifics of the data set.

Micro architecture

The micro architecture of the individual modules is not part of the organisation-wide macro architecture.

For a sample micro architecture, see the Lobid micro architecture (which uses Metafacture for data transformations) below.