Objects

1 Object Report
2 Object Download Service Deprecated
3 Object sample
- 3.1 Changes to filename
  - 3.1.1 Image Covers (Q1/2023)
  - 3.1.2 Audio Samples (Q3/2023)

New Authentication & URLs introduced Q2 2024

Object Report

The objects (images and audio files) report contains identifiers and references to the address where the objects can be downloaded. These references will be valid for a limited period of time. The typical use of the object services is as follows:

Authenticate (same for all services)
Request report (list) of updated objects
Parse list of updated objects (obtain URL to download service for each object)
Download actual objects from download service (one or more requests per object)

URL	`https://api.bokbasen.io/metadata/export/object/v1` `https://api.boknett.no/metadata/export/object` The token acquired from the Authentication Service. Formated "Boknett TGT-...." Required header: `Date` . The timestamp the request was made. Must comply with RFC 1123 date formats.
Method	`GET`
Request headers	`Authorization`	Required	The token acquired from the Authentication Service. Audience: `https://api.bokbasen.io/metadata/` Formated "Bearer …"
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.
	`pagesize`	Optional	See Pagination
Response headers	`Next`	See Pagination
Response headers	`Link`	See Pagination
Response body	XML (Object metadata)
Returns	`200`	OK
	`400`	Bad Request
	`401`	Unauthorized
	`403`	Forbidden
	`406`	Not Acceptable
	`500`	Internal Server Error

* 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.
Note that this database also contains historical objects, so that you can get objects for books that are deleted and sold out, so one should always check if the object is required for your system in your import process
The database is containing objects for over 150 000 titles, so a full dump on the database is very time consuming. When doing this, the biggest impact is choosing which types you actually need so you do not incur unecessary requests. E.g. if you are only loading images and you only need ORG, that will require about 150 000 download requests, but if you include all types for images that becomes 450 000 requests and trippling your execution time.

Object Download Service Deprecated

No longer need to download objects

There is now no need to download resources and host yourself. Just use the public available URL that comes in ONIX directly in customer facing solutions.

Cover Images are now hosted with public available URLs
Audio Samples are now hosted with public available URLs

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.

URL	`https://api.boknett.no/metadata/export/object/download`
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.
	`Accept`	Required	Must be "application/octet-stream"
Query parameters	`id`	Required	An unpredictable generated identifier that uniquely references an object representation. Returned in the response from the Object Report Service. Valid for a limited time.
Response header	`Content-Disposition`	Suggests a default filename
Response body	Object file
Returns	`200`	OK
	`403`	Forbidden
	`404`	Not Found
	`410`	Gone

Object sample

Request objects report and thereafter download service

> curl -i -H "Authorization: Boknett TGT-1947-CEwDRwvOiIodyeov31sMnHTn7XxbZH15GDhJDdKWAq1rELH5wU-login.boknett.no" -H "Date: Thu, 12 Jun 2014 13:46:16 GMT" '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: <https://api.boknett.no/metadata/export/object?next=MTI1MTU0YWE4MDMzIzE0Njc1YmNmZTU3IzhmMzEyZDM=&pagesize=5000>; rel="next"
Content-Type: application/xml
Via: 1.1 api.boknett.no
Transfer-Encoding: chunked
<?xml version="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://api.boknett.no/metadata/export/object/download?id=xpgZ1kLIardQ%2FWMwitZy02GAyCZzNsnIQTvZSf5LTk6GFDdIAaMGqkXxYoPVCIfy</REFERENCE>
    </OBJECT>
   ...
</OBJECTS>
 
> curl -JO -H "Accept: application/octet-stream" -H "Authorization: Boknett TGT-1947-CEwDRwvOiIodyeov31sMnHTn7XxbZH15GDhJDdKWAq1rELH5wU-login.boknett.no" -H "Date: Thu, 12 Jun 2014 13:49:22 GMT" https://api.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 Jun 2014 13:49:22 GMT
Server: Apache-Coyote/1.1
Content-Disposition: attachment; filename="os.jpg"
Content-Type: application/octet-stream
Content-Length: 28805
Via: 1.1 api.boknett.no

Changes to filename

In case you still want to fetch these files and host them your selves, please make some adjustments.

Objects

Object Report

Object Download Service Deprecated

Object sample

Changes to filename

Image Covers (Q1/2023)

Audio Samples (Q3/2023)