Unpacking the Koha Biblio API

Koha’s RESTful API’s have come on leaps and bounds in recent releases, and I’d like to highlight one endpoint in particular in this post. 

The `/biblios` endpoint was introduced in the 20.05 release of Koha and it allows us to see the full MARC record in all its gory detail. This opens up lots of possibilities both outside of Koha and within. 

The endpoint is available in both staff and public forms, with fields hidden appropriately as per your system preferences and frameworks. To reach the staff view, use `https://staff.library.com/api/v1/biblios/{biblio_id}` with a valid login or to get the public alternative you can access this link: 

`https://catalogue.library.com/api/v1/public/biblios/{biblio_id}`.

In both cases, you’ll need to already know which biblio you want to look at and identify it using its biblionumber for the biblio_id; we don’t currently support search on this endpoint, but there are other options for that already, including SRU. 

MARC is a complicated structure, and different people prefer different representations. That’s what’s so special about this endpoint in Koha, we don’t just assume we know how you want to see it. If you just perform a simple GET on one of the above URLS, you’ll be faced with a list of content-types we accept: 

[
   "application/json",
   "application/marcxml+xml",
   "application/marc-in-json",
   "application/marc",
   "text/plain"
]

To get the actual record, you’ll need to let us know what representation you would like by defining an `Accept` header containing one of the above options.

I’m a json fan, so I’m going to use `application/marc-in-json`, this is easy to achieve with jQuery which we could use from one of the \*UserJS preferences.

Let’s do some interactive development: try adding the following to your IntranetUserJS preference and then navigating to a biblio record.

$(document).ready(function() {
    // Define a variable for our current page url
    let url = new URL(window.location.href);

    // Only run on the biblio detail page
    if (url.pathname == "/cgi-bin/koha/catalogue/detail.pl") {

        // Grab the biblionumber from the url
        let biblionumber = url.searchParams.get('biblionumber');

        // Get the marc-in-json representation of the record from the API
        let getBiblio = $.ajax({
            type: "GET",
            url: `/api/v1/biblios/${biblionumber}`,
            accepts: {
                "*": "application/marc-in-json"
            },
        });

        // On success, display details in the console
        getBiblio.success(function(data, status, jqXhr) {
            console.log(data);
        });

        // On error, display details in the console
        getBiblio.error(function(data, status, jqXhr) {
            console.log(data);
        });
    }
});

If you open the developer tools in your browser you should now see your marc record in json format printed.