Content download

Owned by Bokbasen .
Last updated: Mar 18, 2024 by Svein Are Grønsund
6 min read

After placing an order the get content API gives you access the the actual resource. The workflow is the same for all resources, but in the final step you will receive a link to the content which will be different based on type of content. You must ensure that your client application handles the different content types you which to support.

Recommended Process

The recommended process is as follows and this needs to be followed at each download. The status page has limited life time so you need to go through get content on each download:

  1. Call Get content endpoint using the fulfillment id of the transaction (this ID is unique and will never change)

  2. If you get a 302 http response, then redirect to status page returned in Location header (if 300, redo request with sufficient parameters)

    1. If status page shows PROCESSING, then wait 0.5-1 second and refresh the status URL

    2. Repeat until status shows READY and then initiate download

    3. If status shows FAILED, then abort process and contact Bokbasen

 

eBook-samples

Downloading e-book samples can be downloaded directly using the resource-id found in the Inventory service. Note that due to historical reasons, samles for audio are not available from DDS, only from the ObjectsAPI.

New Authentication & URLs introduced Q2 2024

Get ebook samples content

Initiates a download process for ebook samples.

URL

https://api.bokbasen.io/dds/content/v1/{resourceId}/sample

https://api.dds.boknett.no/content/{resourceId}/sample

The token acquired from the Authentication Service. Example: Authorization: Boknett TGT-....

Required header: Date. The timestamp the request was made. Must comply with RFC 1123 date formats. Example: Tue, 10 Jun 2014 16:23:42 GMT

Method

GET

Request
headers

Authorization

Required

The token acquired from the Authentication Service.

Audience: https://api.bokbasen.io/dds/

Example: Authorization: Bearer ...

Accept

Required

application/json (We recommend all new implementations to use this header, XML support will be phased out in the future)

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)

Get content (based on fulfillment ID)

Initiates a download process, and starts preparing the individual watermarked file for download (if SDRM). 

URL

https://api.bokbasen.io/dds/content/v1/{fulfillmentId}

https://api.dds.boknett.no/content/{fulfillmentId}

The token acquired from the Authentication Service. Example: Authorization: Boknett TGT-....

Required header: Date. The timestamp the request was made. Must comply with RFC 1123 date formats. Example: Tue, 10 Jun 2014 16:23:42 GMT

Method

GET

Request
headers

Authorization

Required

The token acquired from the Authentication Service.

Audience: https://api.bokbasen.io/dds/

Example: Authorization: Bearer ...

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.

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. Currently, the only available option here is 64.

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)

300

Multiple Choices

Details on type and bitrate parameters

These parameters are only needed for audio files and they are required in order to specify which file format you want for audio. The complete list of possible value combination are in the table below. Note that you as integrator is responsible for selecting the right type, depending on which access you are giving your customers to the file. Selection of the right type is imperative for ensuring rights are handled correctly and for best performance of your application. 

 

Current value

Is file for download

(Can customer access the actual file, or is it closed in an app)

Current value

Is file for download

(Can customer access the actual file, or is it closed in an app)

audio/vnd.bokbasen.complete-public

Yes

audio/vnd.bokbasen.complete-private

Only for use for download in closed ecosystem where user cannot access file (e.g in app). If you are using complete file for streaming (progressive download) see audio/mpeg3 at the bottom. Do not use this for streaming.

audio/vnd.bokbasen.zipped-public

Yes

audio/vnd.bokbasen.zipped-private

Only for use in closed ecosystem where user cannot access file (e.g in app).

audio/vnd.bokbasen.hls-private

HLS is only for use in closed ecosystems (e.g in app).

audio/vnd.bokbasen.progressive-private

Complete progressive download is only for use in closed ecosystems (e.g in app). If you are simulating streaming in your app using progressive downloads, this option gives you better performance than the complete download as caching is adjusted to fit a streaming scenario.

 

Note that some publishers might not allow all formats (currently this is only relevant for international publishers), meaning that not all formats are available for all books. This will be reflected in the HTTP 300 response. Usually these restrictions is that public download of files is not allowed, and then no -public versions are available and you cannot give access to consumers to download the file outside a secure app environment. 

HTTP 300 Multiple Choices for audio files

As described audio files need the type and bitrate parameters to be specified. If you request an audio resource without these, you will get an HTTP 300 response with a JSON document explaining all valid options. See example JSON response below. Based on this you can add type and bitrate parameters to your request and re submit to the same URL. In most cases this list will be with the value below, but note that for legal reasons some publishers are not offering all formats, then the list will only show formats that are available. 

[ { "type": "audio/vnd.bokbasen.zipped-public", "bitrate": "64" }, { "type": "audio/vnd.bokbasen.zipped-private", "bitrate": "64" }, { "type": "audio/vnd.bokbasen.complete-public", "bitrate": "64" }, { "type": "audio/vnd.bokbasen.complete-private", "bitrate": "64" }, { "type": "audio/vnd.bokbasen.hls-private", "bitrate": "64" }, { "type": "audio/vnd.bokbasen.progressive-private", "bitrate": "64" } ]

Download status service

This service can only be accessed after calling Get content, and been given a link to a status service page

URL

https://api.dds.boknett.no/download/{downloadid}/status

Method

GET

Request
headers

This service uses a random generated URL with limited life time, no authentication is required, but use Accept header to get response in json or XML.

Response
body

{"status":"READY","downloadURL":"https://urlToResource"}

- or -

{"status":"PROCESSING"}

- or -

{"status":"FAILED"}

Returns

200

OK

Handling various status messages

Depending on the resource requested, some processing might be required on the server to prepare the individual file for the order. The status parameter in the json document shows you the status on the files preparation. Below you see a table of possible values and how you should handle each of them.

Value

Meaning

Action

Value

Meaning

Action

READY

File is ready to be accessed

Access URL given in downloadURL parameter.

PROCESSING

File is being processed, but is not ready for download.

Wait 0.5-1 second, before refreshing the page.

FAILED

An unexpected error happened during processing and DDS is not able to produce a file.

Provide the user with an error message and contact Bokbasen.

Curl example - ebook (curl)

Successful download of ebook resource. The first request calls get content to start producing the individual copy of the content for this transaction. Second step is to follow the redirect to the status page showing whether the resource is ready for download (is status is not READY, wait one second and call URL again). Final step is to access download URL and how you are using this is depending on what kind of resource this is. The example below will download the epub file and save this to disk. 

Step 1) Get content

curl -i \ -H "Accept: application/json" \ -H "Authorization: Bearer <token>" \ 'https://api.bokbasen.io/dds/content/v1/755f943c-2644-413f-8e0c-4e16f38cfdf1' HTTP/1.1 302 Found Date: Wed, 12 Aug 2015 09:22:49 GMT Location: https://api.dds.boknett.no/download/bb3547bf-00e9-4e8a-8ba8-027a96390fd7/status

Step 2) Check status / get downloadURL

curl -i https://api.dds.boknett.no/download/bb3547bf-00e9-4e8a-8ba8-027a96390fd7/status HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 {"status":"READY","downloadURL":"https://api.dds.boknett.no/download/ff9e6b14-0e3d-4993-b79f-61fc6118e5ca/binary"}

Step 3) Fetch the binary (if READY)

Curl example - audiobook

Example of successful download of Audio book, where we first try to retrieve book without specifying type and bit rate and get all available options in return. Then we use that information to request one specific format/bitrate for the audiobook.

Step 1) Get content → shows multiple choice

Step 1B) Get content (w/type + bitrate) → StatusURL

Step 2) Check status (w/type + bitrate) / get downloadURL

Step 3) Fetch the binary (if READY)

(same as last example)