API for Digital Lending Platforms

Introduction

Introduction can be read here.

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:

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. 

* 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. 

ATOM Inventory XML format

Example XML:

The fields that are important for you are:

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. 

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:

License types

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.

{
"type": "#lender-content-status",
"self": "/content/status?size=20&page=0",
"next": "/content/status?size=20&page=1",
"items": [
 {"id" : "isbn"},{"id" : "isbn"},{"id" : "isbn"}
 ]
}

Curl Example

curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Boknett TGT-20025-OIgkKTofLlCJQasKhiuigfGQ7p0PueBCBvp0IFkN7TeQ0lrdFS-login.boknett.no" -H "Date: Fri, 07 Aug 2015 12:54:00 GMT" -d '{"lender_ids":["1170201","1170202"],"content_ids":["9788292611098","9788242139252"]}' https://api.loan.boknett.no/content/status
HTTP/1.1 200 OK
Date: Fri, 07 Aug 2015 13:04:47 GMT

{
    "type": "#lender-content-status",
    "items": [
	{"id" : "9788242139252"}
	]
}

Get titles that library has in "inventory"

These are all books that an organisation has set to be a part of their inventory regardless of availability. Inventory is defined as:

• Any book with a valid LEGACY license
• Any book with a PAY_PER_LOAN license that the lender has not actively blocked 
• Any book with a PACKAGE license that still have remaining loan or is set as auto buy

Inventory can potentially return many values with no paging, and is an endpoint meant to be used in a batch process not for live queries.

Curl Example

curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Boknett TGT-20025-OIgkKTofLlCJQasKhiuigfGQ7p0PueBCBvp0IFkN7TeQ0lrdFS-login.boknett.no" -H "Date: Fri, 07 Aug 2015 12:54:00 GMT" -d '{"lender_ids":["1170201","1170202"]}' https://api.loan.boknett.no/content/inventory
HTTP/1.1 200 OK
Date: Fri, 07 Aug 2015 13:04:47 GMT

{
    "type": "#lender-content-inventory",
    "items": [
	{"id" : "9788242139252"}
	]
}

Get detailed license information for one title

This end-point will give detailed information about the available licenses for the given title in the given lender organisation(s). Before creating a new loan one need to use this end-point to check latest availability and to determine which license to use.

Note, this endpoint will only return licenses that are available. An empty list means that all licenses are currently in use or empty.

Recommendation: Note that availabilities can change quickly, so even if this call returns ok on a license, someone else might be able to do the loan before you and then use the license (POST loan will then fail with a HTTP 400 response code). We recommend that you make a prioritised list of the licenses (if there are more than one) and that if you get an error when attempting to create a loan on one license, you move to the next one. How you make this priority is up to you and your customer, but note that the choices made here can have significant financial impact for the lender organisation (e.g. if choosing a PAY_PER_LOAN instead of PACKAGE). 

Curl Example

curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Boknett TGT-20025-OIgkKTofLlCJQasKhiuigfGQ7p0PueBCBvp0IFkN7TeQ0lrdFS-login.boknett.no" -H "Date: Fri, 07 Aug 2015 12:54:00 GMT" -d '{"id":"9788292611098", "lender_ids":["1170201","1170202"]}' https://api.loan.boknett.no/content/licenses
HTTP/1.1 200 OK
Date: Fri, 07 Aug 2015 13:04:47 GMT

{
	"type": "#lender-content-licenses",
	"self": "https://api.loan.boknett.no/content/licenses",
    "id": "9788292611098", 
	"items": [{
		"lender_id": "1170201",
		"licenses": [{
			"loan_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjU2MzBmYjg5LTUyZTEtNDk1",
			"type": "KULTUR"
		}, {
			"loan_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjU2MzBmYjg5LTUyZTfdsgfdsgfk1",
			"type": "PACKAGE"
		}, {
			"loan_token": "eyJhbGciOiJIUzI1Nigfdgfdggfdgdsgdf5cCI6IkpXVCJ9.eyJpZCI6IjU2MzBmYjg5LTUyZTEtNDk1",
			"type": "PAY_PER_LOAN"
		}]
	}, {
		"lender_id": "1170202",
		"licenses": [{
			"loan_token": "eyJhbGciOiJIUzI1NggggiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjU2MzBmYjg5LTUyZTEtNDk1",
			"type": "KULTUR"
		}, {
			"loan_token": "eyJhbGciOiJIUzI1Nigfdgfdggfdgdsgdf5cCI6IkpXVCJ9.eyJpZCI6IjU2MzBmYjg5LTUyZTEtZx43",
			"type": "PAY_PER_LOAN"
		}]

	}]
}

Begin a loan

Begin a loan for a given license, note that this is a asynchronous API endpoint in order to ensure safe processing and validation against the budget. You initiate a loan process calling this endpoint and then you must poll the status endpoint until you get a confirmation/error. When successful you are given an ID that you must store in your system in order to return the book later.

Curl Example (including polling)

#Initiate loan using a loan_token
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Boknett TGT-2673-j3yOnvB5L0qxjE1KdtRNZrBNbAHiti5RLHYNU4PuHE4tY4GqOw-login.boknett.no" -H "Date: Tue, 04 Apr 2017 09:04:00 GMT" -d '{"loan_token":"eyJhbGciOiJIUzI1NifffIsInR5cCI6IkpXVCJ9.eyJpZCI6IjU2MzBmYjg5LTUyZTEtNDk1"}' https://api.loan.boknett.no/loan

HTTP/1.1 302
Date: Tue, 04 Apr 2017 09:06:10 GMT
Location: https://api.loan.boknett.no/loan/status/2f7bb01e-ab81-4d36-8ae7-e9696be803b2


#Use location header to poll to see if loan is ready, in this case it is not ready yet, but still processing
curl -i -H "Accept: application/json" 'https://api.loan.boknett.no/loan/status/2f7bb01e-ab81-4d36-8ae7-e9696be803b2'
HTTP/1.1 204
Content-Length: 0
Date: Thu, 10 Aug 2017 08:33:38 GMT


#Poll again to see if loan is ready, now to loan is complete and accepted and you can give the book to the customer. Save id provided i Location header to return/cancel loan later.
curl -i -H "Accept: application/json" 'https://api.loan.boknett.no/loan/status/2f7bb01e-ab81-4d36-8ae7-e9696be803b2'

HTTP/1.1 303
Content-Length: 0
Date: Thu, 10 Aug 2017 08:33:38 GMT
Location: https://api.loan.boknett.no/loan/91e81c9d-8248-4d5a-8f8d-4677b461318c

When polling the /loan/status endpoint you can expect the following HTTP codes

Cancel a loan

Cancels a loan, if a book is returned without reaching its reading threshold (currently 10%). 

Curl Example

curl -i -X PUT -H "Authorization: Boknett TGT-2673-j3yOnvB5L0qxjE1KdtRNZrBNbAHiti5RLHYNU4PuHE4tY4GqOw-login.boknett.no" -H "Date: Tue, 04 Apr 2017 09:04:00 GMT" https://api.loan.boknett.no/loan/2f7bb01e-ab81-4d36-8ae7-e9696be803b2/cancel

HTTP/1.1 204
Date: Tue, 04 Apr 2017 09:09:44 GMT

Return a loan

Returns a loaned book (also confirms that a book has reached its reading threshold)

Curl Example

curl -i -X PUT -H "Authorization: Boknett TGT-2673-j3yOnvB5L0qxjE1KdtRNZrBNbAHiti5RLHYNU4PuHE4tY4GqOw-login.boknett.no" -H "Date: Tue, 04 Apr 2017 09:04:00 GMT" https://api.loan.boknett.no/loan/2f7bb01e-ab81-4d36-8ae7-e9696be803b2/return

HTTP/1.1 204
Date: Tue, 04 Apr 2017 09:09:44 GMT

API endpoints for support maintenance 

These endpoints are not requirement in the normal flow for doing loans and checking status, but are made available to support your maintenance and support routines. 

Get list of loans

This returns a list of loan started with your API user. This is meant to be a support tool for you to check which loans you have started and also to implement processes where you can verify that all started loans are returned. The API only returns a list of IDs and you can use Get loan to see details on each loan. The endpoint also implements standard paging. You can use the ?status= query parameter to only retreive loans with a certain status. 

{
 "items": [
 "844cc45d-d40b-4474-8c8c-7fd92ec6232e",
 "8c253065-b231-44e0-9b86-2cbde7baa251",
 "99415899-fe39-437d-bf7d-fb9cab51f1e2",
 "9e557d4d-2268-4a4b-a1b8-e4bc2c31ad3f",
 "a1026050-45a8-4a28-a405-771e9ef59545",
 "af68e1f5-82e8-4460-9f01-a6714b1a57d5",
 ],
 "self": "https://api.loan.boknett.no/loan?status=all&size=20&page=0",
 "next": "https://api.loan.boknett.no/loan?status=all&size=20&page=1",
 "type": "#loans"
}

Get a loan

Get status on a loan

Curl Example

curl -i -H "Accept: application/json" -H "Authorization: Boknett TGT-2673-j3yOnvB5L0qxjE1KdtRNZrBNbAHiti5RLHYNU4PuHE4tY4GqOw-login.boknett.no" -H "Date: Tue, 04 Apr 2017 09:04:00 GMT" https://api.loan.boknett.no/loan/2f7bb01e-ab81-4d36-8ae7-e9696be803b2

{"license_id": "53fc660e-8f4b-4a0b-9719-3aecd654b0ad","product_id": "14e4adac-fdf5-475c-b3df-2f4601c67843","created": "2017-04-04T11:06:02+0200","returned": "2017-04-04T11:06:08+0200","confirmed": true}