API for Digital Lending Platforms

1 Introduction
- 1.1 Test environment
- 1.2 Authentication
- 1.3 URLs
2 Getting metadata
- 2.1 Curl examples
- 2.2 Response
- 2.3 Cover images and audio samples
3 Getting EPUB / audio files
- 3.1 Inventory API
- 3.2 ATOM Inventory XML format
- 3.3 Download content API
4 APIs for lender applications
- 4.1 Introduction
  - 4.1.1 License types
- 4.2 Paging
- 4.3 API methods
  - 4.3.1 Check if one or more titles are available for loan
    - 4.3.1.1 Curl Example
  - 4.3.2 Get titles that library has in "inventory"
    - 4.3.2.1 Curl Example
  - 4.3.3 Get detailed license information for one title
    - 4.3.3.1 Curl Example
  - 4.3.4 Begin a loan
    - 4.3.4.1 Curl Example (including polling)
  - 4.3.5 Cancel a loan
    - 4.3.5.1 Curl Example
  - 4.3.6 Return a loan
    - 4.3.6.1 Curl Example
- 4.4 API endpoints for support maintenance
  - 4.4.1 Get list of loans
  - 4.4.2 Get a loan
    - 4.4.2.1 Curl Example

Introduction

Test environment

For accessing the test environment just replace the domain boknett.no with boknett.webbe.no for all services. Note that you need a separate username/password for the test and production environment.

Authentication

All APIs are using the same authentication scheme and you can use the same token for all services below, details on that can be read here Authentication Service.

URLs

The digital lending platform consists of several applications, so you will see some APIs being on different subdomains. In short it is as follows:

Application	Base URL Production	Base URL Test environment

Application	Base URL Production	Base URL Test environment
Loan application	https://api.loan.boknett.no	https://api.loan.boknett.webbe.no
Digital distribution	https://api.dds.boknett.no	https://api.dds.boknett.webbe.no
Metadata	https://api.boknett.no	https://api.boknett.webbe.no

Getting metadata

Bokbasen has several metadata services, and if you have signed separate agreement on metadata you can use the ONIX metadata integration. For integrators that only has agreement for the lending platform the following applies.

Included in the platform is access to basic metadata about all digital products that are available in any library license, this API uses Bokbasen's standard paging mechanism that you can read about here. Data is returned in the NORMARC format which is that standard metadata format for Norwegian libraries.

URL	https://api.boknett.no/metadata/export/marc/loan
Method	GET
Request headers	Authorization	Required	The token acquired from the Authentication Service. Formated "Boknett TGT-...."
	Date	Required	The timestamp the request was made. Must comply with RFC 1123 date formats. Example: Tue, 10 Jun 2014 16:23:42 GMT
Query parameters	next	Required*	All data elements modified after this “cursor”. The cursor is in a not human readable format.
	after	Required*	All data elements modified after this timestamp. The timestamp is on the format yyyyMMddHHmmss.
Response headers	Next	See Pagination
	Link	See Pagination
Response body	NORMARC
Returns	200	OK

* One of the parameters “next” and “after” is required.

Curl examples

First time you use the API you must use the after parameter (if you are downloading the entire database just use a very old timestamp, e.g 19500109130000)

curl -H "Authorization: Boknett TGT-13-amdKXpdVvSkEZ6" -H "Date: Tue, 01 Apr 2014 13:15:00 GMT" https://api.boknett.no/metadata/export/marc/loan?after=20140109130000

For all future call you only need to use the next token in order to get metadata on new/changed titles.

curl -H "Authorization: Boknett TGT-13-amdKXpdVvSkEZ6" -H "Date: Tue, 01 Apr 2014 13:15:00 GMT" https://api.boknett.no/metadata/export/marc/loan?next=28sHyi34ddFFGe23=

Response

The response is of type text/plain. There is no metadata except for the NORMARC data itself. An example payload of the response for a single marc post is shown below.
Marc data for a single post

*000 nam 1
*007cn
*008161006s2017 no jr 10nob 9
*015 $a150188673$bBokbasen AS
*019 $abu,u$bga,la,nb,o$dR
*020 $a978-82-05-47579-3
*025 $a9788205475793
*040 $aBokbasen AS
*0411 $anob$hswe
*090 $dL
*10010$aLarsson, Åsa$d1966-$jSE$0(NO-TrBIB) 98066522$8f
*24010$aVitormen
*24510$aHvitormen$cÅsa Larsson & Ingela Korsell ; illustrert av Henrik Jonsson
; oversatt av Jørn Roeim$helektronisk ressurs
*260 $aOslo$bGyldendal$c2017
*300 $bill.
*440 0$aPax$v8
*520 $aEt urgammelt skrekkvesen våkner til liv og bryter seg løs, et barn blir
slukt og forsvinner, og et eller annet sted i Mariefred er det en jente
som plages av skyldfølelse og hemmeligheter. Samtidig blir Iris holdt
fanget av Migrene-Magga, og mørke planer begynner å utkrystallisere seg.
Klarer Viggo og Alrik å nærme seg Svartheksa uten samtidig å gå under
selv?
*574 $aOriginaltittel: Vitormen
*651 $aSverige$2Bokbasen AS$9nob
*651 $aSverige$2Bokbasen AS$9nno
*655 0$aFantasy$2Bokbasen AS$9nob
*655 0$aFantasy$2Bokbasen AS$9nno
*655 0$aSpenning$2Bokbasen AS$9nob
*655 0$aSpenning$2Bokbasen AS$9nno
*655 0$aRomaner$2Bokbasen AS$9nob
*655 0$aRomanar$2Bokbasen AS$9nno
*70010$aKorsell, Ingela$d1967-$eforf.$jSE$0(NO-TrBIB) 15010618$8f
*70010$aJonsson, Henrik$d1986-$eillustr.$jSE$0(NO-TrBIB) 15010617$8m
*70010$aRoeim, Jørn$d1950-$eovers.$jNO$0(NO-TrBIB) 90133328$8m

Cover images and audio samples

Cover images and audio samples (for audio books) are available on a separate API. The documentation for this end-point is separate, and you can find that below. The only change you need to do for this is to replace /metadata/export/object with /metadata/export/object/loan.

See here for the documentation for the object download API.

Getting EPUB / audio files

The platform assumes that you as integrator can pass Bokbasen's requirements for a partner agreement, where you will be given access to the EPUB and audio files that can be stored on your system and integrated into your distribution platform. This requires documentation and possibly an audit in order to verify that you as integrator has sufficient security related to your handling of book files.

The APIs for getting access to the books are two steps. One is the Inventory API where you get a list of books and information about which books you have access to, and the ID required to initiate the download process. Note that the Inventory API returns all books in Bokbasen's distribution platform, so you will get a lot more books that you have access to.

Inventory API

The inventory API uses the same paging mechanism as referenced under get metadata. The list of books is returned in an ATOM XML format, and using the next token you will always get new books and any books with changes. Changes might include new versions of the file uploaded by the publisher.

URL	https://api.dds.boknett.no/v2/inventory/
Method	GET
Request headers	Authorization	Required	The token acquired from the Authentication Service. Formated "Boknett TGT-...."
Request headers	Date	Required	The timestamp the request was made. Must comply with RFC 1123 date formats. Example: Tue, 10 Jun 2014 16:23:42 GMT
Query parameters	after	Required if next not given
	next	Required if after not given
	pagesize	optional	(default and max value is 10000)
Response headers	Content-Type	application/atom+xml;charset=UTF-8
	Next	next token for next page
	Link	link to next page
Response body	ATOM Inventory XML format (same format as before, however only latest version of each book is returned and some fields are removed)
Returns	200	OK
Returns	40x	On error

ATOM Inventory XML format

Example XML:

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:inv="http://bokbasen.no/module/inventory/1.0">
  <title>Inventory Items</title>
  <link rel="self" type="application/atom+xml" href="http://api.dds.boknett.no/inventory/" title="Inventory feed" />
  <updated>2015-08-07T11:19:45Z</updated>
  <entry>
    <id>urn:uuid:99496f82-84c5-4de7-9899-31603e26a355</id>
    <updated>2015-08-06T11:52:09Z</updated>
    <inv:isbn>9788242160966</inv:isbn>
    <inv:publisher>900224</inv:publisher>
    <inv:format>MP3</inv:format>
    <inv:drm>SDRM</inv:drm>
    <inv:version>1</inv:version>
    <inv:deleted />
    <inv:published>true</inv:published>
    <inv:access>false</inv:access>
    <inv:excerpt>false</inv:excerpt>
  </entry>
</feed>

The fields that are important for you are:

Field

Field
`<inv:access>`	This and published must be true in order for you to download the book
`<inv:published>`	This and access must be true in order for you to download the book
`<inv:isbn>`	ISBN of the book
`<id>`	This resource UUID is unique for this version of the file, you need this id to download the book in the download API
`<inv:format>`	Format of the book, MP3, EPUB, EBP or PDF
`<updated>`	Timestamp of the last update

Download content API

Initiates a download process, for e- and audio books based on the resource id. Note that download of books is an asynchronous process so that you need to poll the /download endpoint until the book is ready for final download. Note that this step will not work if you are using auto-follow redirects in your http client, you need to grab the location header from the first request.

For audio downloads you also need to specify bitrate and type, for library integrators these values are always 64 and audio/vnd.bokbasen.complete+private.

URL	https://api.dds.boknett.no/content/library/{resid}
Method	GET
Request headers	Authorization	Required	The token acquired from the Authentication Service. Formated "Boknett TGT-...."
	Date	Required	The timestamp the request was made. Must comply with RFC 1123 date formats. Example: Tue, 10 Jun 2014 16:23:42 GMT
	Accept	Required	application/json (We recommend all new implementations to use this header, XML support will be phased out in the future)
Parameters	type	Optional*	Which type of the resource are you requesting. This is only required for audio books, if missing you will get a http 300 response providing you with the various options.
Parameters	bitrate	Optional*	Which bitrate for the file are you requesting. This is only required for audio books, if missing you will get a http 300 response providing you with the various options.
Response headers	Location	https://api.dds.boknett.no/download/{downloadid}/status
Response body	None
Returns	302	Found (on success, you will receive this code and a redirection to the resource download status page)
Returns	300	Multiple Choices

For details on the download process see the documentation for the download endpoint here: Content download. The only difference is that to initiate the download you are using the end-point describe above.

APIs for lender applications

Introduction

This section describes the API endpoint where one manages the loan process, typically this is the backend server for your end-user application (app or website). Some definitions of terms used in the APIs:

Term	Definition

Term	Definition
lender_id	This is the ID of the lender organisation, typically a library. The id is the official id of the library given by the national library in Norway. You can either access this through the national libraries XML feed or get the number directly from your customer. The full XML-feed is available at: www.nb.no/baser/bibliotek/eksport/bb-full.xml As one person can have access to books from multiple libraries, API points accept a list of lender_ids
content_id	Unique ID for the requested content, currently this is based on ISBN, but kept as a generic term in order to support other content types in the future that might not have ISBNs.
licenses_type	The type of license, see section below for a list of possible values. But the solution requires you as an integrator to have an understanding of the commerical impact of these various models, and explaining that is outside the scope of this document.

License types

Type	Description

Type	Description
PACKAGE	These are pre-paid packages of books, usually 10 clicks in one package
PAY_PER_LOAN	These are loans where the cost incur after a loan is done
LEGACY	Existing licenses from the model where one bough licenses with unlimited number of loans, but a fixed duration.

Paging

Some endpoints support paging, loan-API is using a simple paging controlled by two parameters size= (number of items in response) and page= to indicate page number).

API methods

Check if one or more titles are available for loan

Use this service to get status whether one or many titles are available for loan (right now) from one or more lender organisations. Useful for updating user interface with availability status and also for frequent polling of availability.

The API will only return ISBNs that are available, meaning that if you requested id A and B, and the API returns A. B is not available for the given organisation(s). It is possible to call this endpoint withouth specifying content_ids ids to get all content that are available, but this can provide very large results sets and is not recommended.

URL	https://api.loan.boknett.no/content/status
Method	POST
Request headers	Authorization	Required	The token acquired from the Authentication Service. Formated "Boknett TGT-...."
	Date	Required	The timestamp the request was made. Must comply with RFC 1123 date formats. Example: Tue, 10 Jun 2014 16:23:42 GMT
	Accept	Required	application/json
	Content-type	Required	application/json
Requests params	size	Optional	Page size
	page	Optional	Which page to retreive
JSON attributes request	lender_ids	Required	Array of ids of lender organisations (library ids)
JSON attributes request	content_ids	Optional	Array of content-ids you want to retrieve status for (ISBN). Not required, but highly recommended
Responsebody