@biblioteksentralen/bmd-search-client

@biblioteksentralen/bmd-search-client

Basic usage example

import { createCordataApiClient } from "@biblioteksentralen/bmd-search-client";

const cordata = createCordataApiClient({
  clientIdentifier: "My little library app ([e-mail])",
  catalogueId: "tonsberg",
});

const { data, error } = await cordata.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}`);
  }
}

Options

API context

This package provides clients for two BMD APIs:

• The Public Library API, based on the Public Library API Specification, in which the response models have been modelled 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.

  import { createPublicLibraryApiClient } from "@biblioteksentralen/bmd-search-client";
  
  const plas = createPublicLibraryApiClient({ clientIdentifier: "My little library app ([e-mail])" });
  const results = await plas.searchWorks({ query: "Jo Nesbø" });
  

• The Cordata API, which uses the same request structure, but provides responses based on our internal Cordata metadata model, a three-level model (Work-Expression-Manifestation) which can be more suited for library professionals.

  import { createCordataApiClient } from "@biblioteksentralen/bmd-search-client";
  
  const cordata = createCordataApiClient({ clientIdentifier: "My little library app ([e-mail])" });
  const results = await cordata.searchWorks({ query: "Jo Nesbø" });
  

The two APIs are aligned as much as possible. Endpoints generally use the same request structure, but different response structure. Some APIs are only available in one or the other API, for instance the "Get Publications" endpoint is only available in the Public Library API.

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. Note that catalogue scoping only guarantees that results are found in the given library catalogue, not that the library have active holdings. If the actual holdings have been weeded, the catalogue record may still be present.

const client = createCordataApiClient({
  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 = createCordataApiClient({
  environment: "staging",
  ...otherOptions,
});