The export service provides alternatives for retrieving metadata and objects from Bokbasen. All of these services requires authentication using the Authentication ServiceThis pages contains general information covering all export services, see individual sub pages for the different data and formats that can be retrieved.

Revision History

Bokbasen XML Report

Note that this service is deprecated and will be phased out 1.1.2016. All customers should migrate to the ONIX format and use the Onix report API to get their updates.

...

...

The token acquired from the Authentication Service.

Formated "Boknett TGT-...."

...

...

...

Next

...

Link

...

Onix Report

...

...

The token acquired from the Authentication Service.

Formated "Boknett TGT-...."

...

...

...

Next

...

Link

...

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

Object Report

...

...

The token acquired from the Authentication Service.

Formated "Boknett TGT-...."

...

...

Next

...

Link

...

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

Response Body (Object metadata XML)

<OBJECTS>
    <OBJECT>
        <ISBN13></ISBN13>
        <EAN></EAN>
        <FSSN></FSSN>
        <VAREEIER_KODE></VAREEIER_KODE>
        <TYPE></TYPE>
        <REFERENCE><REFERENCE/>
    </OBJECT>
<OBJECTS/>

• TYPE, “Type of object”. ly = Lydfil, ol = Omslag lille (width 120), os = Omslag stor (height 450), org = original omslag (This is the original image file sent to Bokbasen, so this is the one with the highest quality. This only exists for files sent to Bokbasen after February 2015, for older files this will be the same quality as os)
• REFERENCE - short lived link to object available for download at download service. Reference is generated in a dynamic non predictable manner.

Object Download Service

The Object Download Service provides an endpoint for downloading binary object resources. The path to this service, as well as a unique identifier of the requested object, is returned from the object metadata service, which therefore must be called in advance. The unique identifier is only valid for a certain amount of time, as described in the table below, and can only be called by the same user (credentials) that requested the object export metadata service. The following details the parameters, example usage and different responses when using this service.

...

...

The token acquired from the Authentication Service.

Formated "Boknett TGT-...."

...

Response
header

...

Pagination

All reports will require one of two parameters; “after” or “next”. The usage of the two parameters differs slightly. The HTTP response will always contain a token that represents a specific “internal timestamp” and can be used as a “cursor”. This token can be used in the next request to get all changes since the last request. The maximum allowed age a of both parameters is currently 180 days but might change in the future. If a customer needs to fetch older information than this, please contact Bokbasen on a case by case basis.

Parameters

Next

Using the “next” parameter is the recommended way to invoke the report service. It is also the only possible way to implement incremental updates. The HTTP response from all report services will include a header containing a token that represents a specific “internal timestamp” that can be used as a “cursor”. This token shall be passed with the “next” parameter in the subsequent request in order to retrieve all updates since the last request. This requires the customer to save the obtained token from each response and use it in the following request. If the token is lost, a new token can easily be obtained by making a new request using an older “next” or the “after” parameter.

After

Using the “after” parameter will allow clients to request records updated since a specific time. The parameter has a human readable format “yyyyMMddHHmmss”. The only recommended usage of the “after” parameter is (1) when non incremental updates are requested (for example all records updated last 2 months) or (2) when the token is lost. A response to a request with an after parameter will include a new cursor in the header as long as the resulting report is not empty. Using the “after” parameter for incremental updates can result in duplicated updates or “missed” updates. (The cause for this is that the timestamp on which both “next” and “after” is based, can be set to a value that is before current time.)

Pagesize

All reports have a default pagesize which is also the maximum pagesize. The client is free to choose a suitable pagesize between 1 and this maximum. If pagesize is omitted, or the requested pagesize exceeds the maximum, the services will handle the request using the default pagesize. All clients requesting reports should use the pagination facility when fetching a large number of records.

Response headers

Next Response header

The "Next" response header is always present. When the current response does not contain any records the Next response header is unchanged.

Link reponse header

The "Link" response header is only present as long as there are more pages to process. When the current response does not contain any records the Link response header is not present.

Best practice

Using the "Link" response header is the recommend method to implement pagination. The client should keep sending requests as long as the Link response header is present. After the initial request the "Link" response header should be used in every subsequent request. 
It is also possible to implement pagination using the "Next" response header. If so, the client should keep sending requests as long as the "Next" response header does change from the preceding request.

Error Handling

Feedback

In case the request fails due to validation of request headers or input parameters the client will receive a response consisting of an xml explaining the cause of failure. The elements of the error xml are listed below. For some errors there may be additional elements included for better explanation of the error cause. For non-xml formated reports the response will be in plain text instead of xml.

HTTP/1.1 HTTP_STATUS_CODE MESSAGE
Date: Tue, 01 Apr 2014 10:49:04 GMT
Content-Type: application/xml
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<errors>
	<error>
		<code></code>
		<message></message>
	<error>
<errors>

Notes

Bokbasen XML

Bokbasen XML report format can change. As will the corresponding schema (bokbasenxml-<version>.xsd)

Bokbasen will strive to only make changes that does not invalidate any earlier versions of the the reports. I.e. only add attributes and elements that are not mandatory. Bokbasen reserves the right to do such changes without prior notice or with short notice. Any (unlikely) changes in the schema that invalidates earlier versions of the reports will be given advance notice.

Bokbasen will increase the version number of the Bokbasen XML schema for every change. 
There might be "holes" in the version serie.

It is important that clients (receivers of reports) does not save local copies of the schema but always uses the current schema referenced in the report. Any local software parsing a report with a old copy of the schema might fail.

Restrictions 

Test environment

https://api.boknett.webbe.no

Pagination and Pagesize sample

Request with after and thereafter a request using the returned Link header.

> curl -i -H "Authorization: Boknett TGT-906-Jaemq9xyI5vDRsy6qs27cubbKQIogwFFccjOgK4GYLB5IFT6E0-login.boknett.no" -H "Date: Wed, 11 Jun 2014 19:05:44 GMT" 'https://api.boknett.no/metadata/export/bokbasenxml?subscription=extended&pagesize=100&after=20140501120000'
Date: Wed, 11 Jun 2014 19:11:20 GMT
Server: Apache-Coyote/1.1
Next: MTI1MTUzNzhjMGQzIzE0Njc1YmFjNDlmIzhmMmU5YTU=
Link: <https://api.boknett.no/metadata/export/bokbasenxml?next=MTI1MTUzNzhjMGQzIzE0Njc1YmFjNDlmIzhmMmU5YTU=&subscription=extended&pagesize=100>; rel="next"
Content-Type: application/xml
Via: 1.1 api.boknett.no
Transfer-Encoding: chunked
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<LEVERANSE xmlns="http://api.boknett.no/metadata/export/bokbasenxml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://api.boknett.no/schema/bokbasenxml-1.0.xsd">
... (1-100 records of 150 returned)
</LEVERANSE>

> curl -i -H "Authorization: Boknett TGT-906-Jaemq9xyI5vDRsy6qs27cubbKQIogwFFccjOgK4GYLB5IFT6E0-login.boknett.no" -H "Date: Wed, 11 Jun 2014 19:05:44 GMT" 'https://api.boknett.no/metadata/export/bokbasenxml?next=MTI1MTUzNzhjMGQzIzE0Njc1YmFjNDlmIzhmMmU5YTU=&subscription=extended&pagesize=100'
Date: Wed, 11 Jun 2014 19:12:45 GMT
Server: Apache-Coyote/1.1
Next: MTI1MTUzNzhjMTBjIzE0Njc1YmUyZjY0IzhmMzJhNWM=
Link: <https://api.boknett.no/metadata/export/bokbasenxml?next=MTI1MTUzNzhjMTBjIzE0Njc1YmUyZjY0IzhmMzJhNWM=&subscription=extended&pagesize=100>; rel="next"
Content-Type: application/xml
Via: 1.1 api.boknett.no
Transfer-Encoding: chunked
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<LEVERANSE xmlns="http://api.boknett.no/metadata/export/bokbasenxml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://api.boknett.no/schema/bokbasenxml-1.0.xsd">
... (101-150 of 150 records returned)
</LEVERANSE>
 
>curl -i -H "Authorization: Boknett TGT-906-Jaemq9xyI5vDRsy6qs27cubbKQIogwFFccjOgK4GYLB5IFT6E0-login.boknett.no" -H "Date: Wed, 11 Jun 2014 19:10:46 GMT" 'https://api.boknett.no/metadata/export/bokbasenxml?next=MTI1MTUzNzhjMTBjIzE0Njc1YmUyZjY0IzhmMzJhNWM=&subscription=extended&pagesize=100'
Date: Wed, 11 Jun 2014 19:12:45 GMT
Server: Apache-Coyote/1.1
Next: MTI1MTUzNzhjMTBjIzE0Njc1YmUyZjY0IzhmMzJhNWM=
Content-Type: application/xml
Via: 1.1 api.boknett.no
Transfer-Encoding: chunked
 
(No more records. Next unchanged. Link not present in Response)

Object sample

...

Pagination

All reports will require one of two parameters; “after” or “next”. The usage of the two parameters differs slightly. The HTTP response will always contain a token that represents a specific “internal timestamp” and can be used as a “cursor”. This token can be used in the next request to get all changes since the last request. The maximum allowed age a of both parameters is currently 180 days but might change in the future. If a customer needs to fetch older information than this, please contact Bokbasen on a case by case basis.

Parameters

Next

Using the “next” parameter is the recommended way to invoke the report service. It is also the only possible way to implement incremental updates. The HTTP response from all report services will include a header containing a token that represents a specific “internal timestamp” that can be used as a “cursor”. This token shall be passed with the “next” parameter in the subsequent request in order to retrieve all updates since the last request. This requires the customer to save the obtained token from each response and use it in the following request. If the token is lost, a new token can easily be obtained by making a new request using an older “next” or the “after” parameter.

After

Using the “after” parameter will allow clients to request records updated since a specific time. The parameter has a human readable format “yyyyMMddHHmmss”. The only recommended usage of the “after” parameter is (1) when non incremental updates are requested (for example all records updated last 2 months) or (2) when the token is lost. A response to a request with an after parameter will include a new cursor in the header as long as the resulting report is not empty. Using the “after” parameter for incremental updates can result in duplicated updates or “missed” updates. (The cause for this is that the timestamp on which both “next” and “after” is based, can be set to a value that is before current time.)

Pagesize

All reports have a default pagesize which is also the maximum pagesize. The client is free to choose a suitable pagesize between 1 and this maximum. If pagesize is omitted, or the requested pagesize exceeds the maximum, the services will handle the request using the default pagesize. All clients requesting reports should use the pagination facility when fetching a large number of records.

Response headers

Next Response header

The "Next" response header is always present. When the current response does not contain any records the Next response header is unchanged.

Link reponse header

The "Link" response header is only present as long as there are more pages to process. When the current response does not contain any records the Link response header is not present.

Best practice

Using the "Link" response header is the recommend method to implement pagination. The client should keep sending requests as long as the Link response header is present. After the initial request the "Link" response header should be used in every subsequent request. 
It is also possible to implement pagination using the "Next" response header. If so, the client should keep sending requests as long as the "Next" response header does change from the preceding request.

Error Handling

Feedback

In case the request fails due to validation of request headers or input parameters the client will receive a response consisting of an xml explaining the cause of failure. The elements of the error xml are listed below. For some errors there may be additional elements included for better explanation of the error cause. For non-xml formated reports the response will be in plain text instead of xml.

HTTP/1.1 HTTP_STATUS_CODE MESSAGE
Date: Tue, 01 Apr 2014 10:49:04 GMT
Content-Type: application/xml
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<errors>
	<error>
		<code></code>
		<message></message>
	<error>
<errors>

Restrictions 

Pagination and Pagesize sample

Request with after and thereafter a request using the returned Link header.

> curl -i -H "Authorization: Boknett TGT-1947-CEwDRwvOiIodyeov31sMnHTn7XxbZH15GDhJDdKWAq1rELH5wU-login.boknett.no" -H "Date: Thu, 12 Jun 2014 13:46:16 GMT" 'https: Boknett TGT-906-Jaemq9xyI5vDRsy6qs27cubbKQIogwFFccjOgK4GYLB5IFT6E0-login.boknett.no" -H "Date: Wed, 11 Jun 2014 19:05:44 GMT" 'https://api.boknett.no/metadata/export/bokbasenxml?subscription=extended&pagesize=100&after=20140501120000'
Date: Wed, 11 Jun 2014 19:11:20 GMT
Server: Apache-Coyote/1.1
Next: MTI1MTUzNzhjMGQzIzE0Njc1YmFjNDlmIzhmMmU5YTU=
Link: <https://api.boknett.no/metadata/export/object/?after=20140501000000'

Date: Thu, 12 Jun 2014 13:49:22 GMT
Server: Apache-Coyote/1.1
Next: MTI1MTU0YWE4MDMzIzE0Njc1YmNmZTU3IzhmMzEyZDM=
Link: <httpsbokbasenxml?next=MTI1MTUzNzhjMGQzIzE0Njc1YmFjNDlmIzhmMmU5YTU=&subscription=extended&pagesize=100>; rel="next"
Content-Type: application/xml
Via: 1.1 api.boknett.no
Transfer-Encoding: chunked
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<LEVERANSE xmlns="http://api.boknett.no/metadata/export/object?next=MTI1MTU0YWE4MDMzIzE0Njc1YmNmZTU3IzhmMzEyZDM=&pagesize=5000>; rel="next"
Content-Type: application/xml
Via: 1.1 bokbasenxml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://api.boknett.no
Transfer-Encoding: chunked
<?xml version="/schema/bokbasenxml-1.0" encoding="UTF-8" standalone="yes"?>
<OBJECTS>
    <OBJECT>
        <ISBN13>9788202437930</ISBN13>
        <EAN>9788202437930</EAN>
        <FSSN>150157628</FSSN>
        <VAREEIER_KODE>0008</VAREEIER_KODE>
        <TYPE>os</TYPE>
        <REFERENCE>https.xsd">
... (1-100 records of 150 returned)
</LEVERANSE>

> curl -i -H "Authorization: Boknett TGT-906-Jaemq9xyI5vDRsy6qs27cubbKQIogwFFccjOgK4GYLB5IFT6E0-login.boknett.no" -H "Date: Wed, 11 Jun 2014 19:05:44 GMT" 'https://api.boknett.no/metadata/export/bokbasenxml?next=MTI1MTUzNzhjMGQzIzE0Njc1YmFjNDlmIzhmMmU5YTU=&subscription=extended&pagesize=100'
Date: Wed, 11 Jun 2014 19:12:45 GMT
Server: Apache-Coyote/1.1
Next: MTI1MTUzNzhjMTBjIzE0Njc1YmUyZjY0IzhmMzJhNWM=
Link: <https://api.boknett.no/metadata/export/bokbasenxml?next=MTI1MTUzNzhjMTBjIzE0Njc1YmUyZjY0IzhmMzJhNWM=&subscription=extended&pagesize=100>; rel="next"
Content-Type: application/xml
Via: 1.1 api.boknett.no
Transfer-Encoding: chunked
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<LEVERANSE xmlns="http://api.boknett.no/metadata/export/object/download?id=xpgZ1kLIardQ%2FWMwitZy02GAyCZzNsnIQTvZSf5LTk6GFDdIAaMGqkXxYoPVCIfy</REFERENCE>
    </OBJECT>
   ...
</OBJECTS>
 
> curl -JO -H "Accept: application/octet-stream" -H "/bokbasenxml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://api.boknett.no/schema/bokbasenxml-1.0.xsd">
... (101-150 of 150 records returned)
</LEVERANSE>
 
>curl -i -H "Authorization: Boknett TGT-1947906-CEwDRwvOiIodyeov31sMnHTn7XxbZH15GDhJDdKWAq1rELH5wU-login.boknett.no" -H "Date: Thu, 12 Jun 2014 13:49:22 GMT" https://apiJaemq9xyI5vDRsy6qs27cubbKQIogwFFccjOgK4GYLB5IFT6E0-login.boknett.no/metadata/export/object/download?id=xpgZ1kLIardQ%2FWMwitZy02GAyCZzNsnIQTvZSf5LTk6GFDdIAaMGqkXxYoPVCIfy
 
curl: Saved to filename 'os.jpg'
 

Note: The -JO flag tells curl to use the server-specified Content-Disposition filename. The response headers are not visible in the above curl command but looks like this:

HTTP/1.1 200 OK
Date: Thu, 12" -H "Date: Wed, 11 Jun 2014 19:10:46 GMT" 'https://api.boknett.no/metadata/export/bokbasenxml?next=MTI1MTUzNzhjMTBjIzE0Njc1YmUyZjY0IzhmMzJhNWM=&subscription=extended&pagesize=100'
Date: Wed, 11 Jun 2014 1319:4912:2245 GMT
Server: Apache-Coyote/1.1
Content-DispositionNext: attachment; filename="os.jpg"MTI1MTUzNzhjMTBjIzE0Njc1YmUyZjY0IzhmMzJhNWM=
Content-Type: application/octet-stream
Content-Length: 28805xml
Via: 1.1 api.boknett.no
Transfer-Encoding: chunked
 
(No more records. Next unchanged. Link not present in Response)

Parameter Error

Request with valid Authorization token and Date. But is missing mandatory parameter subscription.

...

...

...