Content download
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:
Call Get content endpoint using the fulfillment id of the transaction (this ID is unique and will never change)
If you get a 302 http response, then redirect to status page returned in Location header (if 300, redo request with sufficient parameters)
If status page shows PROCESSING, then wait 0.5-1 second and refresh the status URL
Repeat until status shows READY and then initiate download
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 |
The token acquired from the Authentication Service. Example: Required header: | ||
Method |
| ||
Request | Authorization | Required | The token acquired from the Authentication Service. Audience: Example: |
Accept | Required | application/json (We recommend all new implementations to use this header, XML support will be phased out in the future) | |
Response | Location |
| |
Response | None | ||
Returns |
| 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 |
The token acquired from the Authentication Service. Example: Required header: | ||
Method |
| ||
Request | Authorization | Required | The token acquired from the Authentication Service. Audience: Example: |
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 | Location |
| |
Response | None | ||
Returns |
| Found (on success, you will receive this code and a redirection to the resource download status page) | |
| 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) |
|---|---|
| Yes |
| 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. |
| Yes |
| Only for use in closed ecosystem where user cannot access file (e.g in app). |
| HLS is only for use in closed ecosystems (e.g in app). |
| 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 |
| ||
Method |
| ||
Request | 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 |
- or -
- or -
| ||
Returns |
| 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 |
|---|---|---|
| File is ready to be accessed | Access URL given in downloadURL parameter. |
| File is being processed, but is not ready for download. | Wait 0.5-1 second, before refreshing the page. |
| 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/statusStep 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)