@biblioteksentralen/bmdb-search-client

TypeScript client for searching Bibliotekenes metadatabrønn (BMDB).

Usage examples

Basic usage example

import { createBmdbSearchClient } from "@biblioteksentralen/bmdb-search-client";

const bmdb = createBmdbSearchClient({
  clientIdentifier: "My little library app ([email protected])",
});

const { data, error } = await bmdb.searchWorks({
  query: "jo nesbø",
});
if (error) {
  console.error(error);
} else {
  console.log(`Fetched ${data.results.length} results:`);
  for (const result of data.results) {
    console.log(`- ${result.work.title.mainTitle}`);
  }
}

Usage with SWR

The package includes a fetcher function that can be used to create a generic SWR hook that returns fully typed responses.

import useSWR, { SWRConfiguration } from "swr";
import { BmdbSearchErrorResponse, DefaultBmdbSearchClient, bmdbFetcher } from "@biblioteksentralen/bmdb-search-client";

const clientIdentifier = "My little library search demo";
const catalogueId = "tonsberg";

export function useBmdb<TOperation extends keyof DefaultBmdbSearchClient>(
  operation: TOperation,
  params: Parameters<DefaultBmdbSearchClient[TOperation]>[0],
  swrOptions: SWRConfiguration = {},
) {
  type TData = Awaited<ReturnType<BmdbSearchClient[TOperation]>>["data"];
  return useSWR<TData, BmdbSearchErrorResponse>(
    { operation, params, clientIdentifier, catalogueId },
    bmdbFetcher,
    swrOptions,
  );
}

Options

Client identification policy

The API does not require authentication, but clients should identify themselves using a descriptive name and a contact address in the clientIdentifier string. We will only contact you about usage of the API.

Catalogue scope

Clients are initialized with a global scope by default. Construct the client with a catalogueId to scope it to a specific library catalogue. The special value "global" can be used for setting the global scope. Note that catalogue scoping only guarantees that results are found in the given library catalogue, not that the library have active holdings. If all holdings have been weeded, the catalogue record may still be present.

import { createBmdbSearchClient } from "@biblioteksentralen/bmdb-search-client";

const client = createBmdbSearchClient({
  catalogueId: "tonsberg",
  ...otherOptions,
});

Environment

The client connects to the production environment by default, but it can be constructed to use the staging environment instead:

const client = createBmdbSearchClient({
  host: "https://search.data-staging.bs.no",
  ...otherOptions,
});

API contexts

BMDB has two API contexts:

• plas: Context based on the Public Library API Specification (PLAS)
  • Response models follow PLAS to provide interoperability with other library systems with different data models. Metadata is simplified into a two-level model (Work/Publication) which is generally easier to work with, but cannot express every metadata aspect that a three-level model can provide.
  • One operation (Get publications) is only available in this context since the concept of a Publication is local to a specific library catalogue.
  • In general this API context is intended for searching a single library catalogue at a time since publication identifiers are local. A special "global" catalogue is provided to allow searching across catalogues, but this is experimental. It's not part of PLAS and identifier stability is not guaranteed.
• cordata: Context based on the Cordata❦ model
  • Request structure (paths and request parameters) is the same as plas.
  • Response models based on our internal Cordata❦ metadata model, a three-level model (Work/Expression/Manifestation) based on LRM/RDA, which can be more suitable for library professionals.
  • Includes a few additional operations for functionality not (yet) covered by PLAS.

The default BMDB client constructed with createBmdbSearchClient() contains methods to access operations from both contexts and returns responses from the default context. If a non-default response format is neede, a client for the specific context can be constructed with createCordataBmdbSearchClient() or createPlasBmdbSearchClient(). Example:

import { createCordataBmdbSearchClient, createPlasBmdbSearchClient } from "@biblioteksentralen/bmdb-search-client";

const clientIdentifier = "My little library client demo";

const plasClient = createPlasBmdbSearchClient({ clientIdentifier });
const plasResponse = await plasClient.searchWorks({ query: "Jo Nesbø" });
const plasFirstWorkResult = plasResponse.data?.results[0]?.work;

const cordataClient = createCordataBmdbSearchClient({ clientIdentifier });
const cordataResponse = await cordataClient.searchWorks({ query: "Jo Nesbø" });
const cordataFirstWorkResult = cordataResponse.data?.results[0]?.work;

console.log(`First PLAS result: ${plasFirstWorkResult?.identifier}`);
console.log(`First Cordata result: ${cordataFirstWorkResult?.id}`);