Getting started

By Per Kristian Solheim
14 min

 

About Bokbasen

Bokbasen is both a metadata distributor and e-book distributor that offer services to online and physical stores.

Introduction

This document describes how to integrate with the Digital Distribution System (DDS) Application Programming Interface (API) through the use of web services. The resources that are available through the AP0I spans from product information, placing orders to cloud storage. The API is suitable for stores, subscription services, libraries and publishers. For technical documentation on each API please refer to the online documentation which is frequently update: https://bokbasen.jira.com/wiki/display/api/Digital+Distribution+System

Getting Started

All users need to have a contract with Bokbasen before integration can start. Once the contract is signed each user is assigned a distributor ID and password that is used in all communication with DDS. It is important to note that metadata and e-/audio book distribution is two separate services, which work in companion. Bookstores, which already have a contract, do not need to renew this. Contact us to start the delivery of metadata for e-/audio books in the same stream as you get today.

E-/audio book Services

Our distribution system for e-/audio books is called Digital Distribution System (DDS) and comprises of several services to online retailers. The following is a brief overview of the services described in this documentation.

Overview of all products - Inventory

The inventory service is where you retrieve information about all products available in DDS. The response is delivered as an OPDS-feed (See glossary for definition).
Inventory must manage which e-/audio books to be sold in the bookstore. Read more about this in the section for Metadata.

Placing orders

Services to place orders for e-/audio books when the customer has bought an e-/audio book.

Retrieving resources

When a customer has bought an e-/audio book the get content services provides interfaces to download e-/audio books.

User Registration and management - Bokskya IDM

Services to create and administrate user accounts.

Overview of Users Books - Bokskya Bookshelf

The customers’ e-/audio books from all bookstores put together in one shelf. To place an e- /audio book in the customers’ shelf you make a call to the order API customers ID.
The Bookshelf (OPDS-feed) is used to give the customer access to download his books on any app or device that supports Bokskya.

Reporting

Sales report. All transactions received in DDS is reported back to the bookstore once a day. The format used is EDItX Sales report from EDItEUR (http://www.editeur.org/ ).

Security and Credentials

DDS use credentials to identify the bookstore and to secure the systems. The credentials must be handled with care and distributed to as few as possible. One should not pass on username/password in an open e-mail together with the other credentials.

Bokbasen deliver credentials only to our customers. To the extent necessary, it is the customer who dispenses credentials to their subcontractors. Credentials are distributed as soon as all necessary agreements is signed.

Environment for testing

All testing is to be done in Bokbasen’s test environment (*.webbe.no).
If you should decide to test against the production environment, be aware that all purchases are real and will be invoiced by the publisher. All functionality must be tested in test environment before live testing.

Important! Credentials are different in test and production environments for the same bookstore.

Test is available at all times. We recommend that the bookstores maintain the link between their test environment and ours also after release. DDS is constantly being developed. New and improved services will always be available for testing in test before deployed to production.

About DRM/Copy protection

It is the publisher who decides which DRM to use on the e-book. It is also an option not to use any DRM (NoDRM). DDS support two types of DRM:

About formats

Bokbasen supports the following audio book formats:

  • HTTPS based download of MP3

  • HTTPS based progressive downloads using HTTP range headers

  • HTTPS based download of zipped MP3 files split into smaller files

  • Apple HTTP Streaming (HLS) of MP3

    Bokbasen supports the following e-book formats:

  • EPUB 2

  • EPUB 3

  • PDF (1.6 or newer)

Metadata for e-/audio books

Metadata about e-/audio books are delivered as a separate service. Bokbasen delivers metadata about all types of books. You can read about formats and how to import and implement metadata to your site in the documentation for metadata services (Onix from Bokbasen and Metadata Export Service).
Established customers can contact us to start the delivery of metadata for e-/audio books in the same stream as received today.

Overview of the sales process

DDS INVENTORY

Services for e-/audio book inventory and basic metadata

Update and populate your system with data from the inventory service and the Bokbasen Metadata export API.

IMPORTANT! First update your system with the required metadata from the API. This is not a part of the e-/audio book distribution; it's a separate service.

DDS IDM

Services for user creation and management

Create user accounts for your customers and get the DDS ID for everyone by using the IDM services.

DDS E-/AUDIO BOOK ORDER AND DOWNLOAD

Services for e-/audio book order placements and file downloads/streaming

Create orders for your customers using order and download the file by using the get content REST API.

DDS BOKSKYA E-/AUDIO BOOK FEED

Services for fetching the users Bokskya feed with all purchased books

Get all the books that any of your customers have in their Bokskya e-/audio book feed. Feed contains links to download REST APIs.

Use of metadata for an e-/audio book

Introduction

In the online store metadata is used for searches, presenting the e-/audio book and is providing information about the content as well as necessary technical information to the end customer. This document describes how metadata should be used for e-/audio books.

Process of updating

  1. Import the metadata updates from Bokbasen metadata API (all books available so you need to filter based on the data to load only the desired books, audio, e-book etc.)

  2. Make a query to DDS Inventory REST API

  3. Display metadata for all e-/audio books with published status = true combined with

    access = true

  4. The store should be able to display metadata of an e-book not published but with
    a published excerpt. Important not to sell the e-book by accident. Note that for audio books the feed will never give an excerpt. Audio book excerpts are only available through Bokbasen metadata download object API.

  5. The store should be able to display metadata of an e-/audiobook for presales. Important to log the orders, but you cannot initiate downloads before the e-/audio book is published.

It is important to note that from the metadata service you will get data on all books registered in the database. This includes e-/audio books, which aren’t published yet, are unpublished or the store doesn’t have access too.
It’s necessary to implement a set of rules for which metadata to display on the site based on formats, status, information etc. There are different issues for physical book and e-/audio books.

For e-/audio books the most important rule is to display only the e-/audio books published in DDS. This is to avoid selling e-/audio books that can’t be delivered. Metadata about an e- /audio book can be available months ahead of publishing. The status provided in the metadata services is not enough to decide if the store can sell the e-/audio book:

  • The e-/audio book distribution does not control the status delivered in the metadata before the book is published in DDS. The publisher can set the wrong code.

  • E-/audio books can be registered with metadata even though they are not going to be distributed through DDS ever.

  • A publisher can block delivery of e-/audio books to a given bookstore. The metadata for the e-/audio books is still delivered by the metadata services.

  • The e-book can be unpublished.

Bokbasen Authentication

Introduction

All DDS services have to be authenticated against the Bokbasen authentication service as described below. The Bokbasen authentication service is used across Bokbasen’s services, so you also use the same process for retrieving Metadata. The documentation for the authentication API is also available online at

Authentication Service (legacy)

Bokbasen is renewing its Authentication service. Look her for more information.

Authentication Service

DDS Inventory

Introduction

This web service retrieves information about all e-/audio books available in DDS based on your users access rights and permissions.

Inventory - Documentation

DDS ID Management (IDM)

Introduction

Bokskya is our cloud storage services for the end consumer. This API describes how to create and administrate user accounts and authorize reading devices and applications.
Bokskya ID is the customers unique ID. The ID is created using e-mail address as identifier.

These services must be integrated in your user registration process, so that you ensure that all your user accounts have a corresponding Bokskya account.

The service includes:

  • Web services to create and administer Bokskya ID

  • Support for Adobe Vendor ID

    Recommended process:

  • ValidateAccount: Use this service to verify if there is an active account.

  • RegisterAccount: Use this service only if one can't verify that there is an active account.

  • AuthUserByPartner: Use this service only IF one is about to do a login by VendorID.

IDM - Documentation

DDS Orders

Introduction

DDS make available products that can be sold in an online store. This API describes how to place orders to DDS for the e-/audio books sold. The process for placing an order is to first call the order REST API, then using the GET content API to retrieve the item that was bought.

Process

Order

Sale of products

An order is placed at the time of a valid purchase from the end-user. This is for a product to be made available to the customer in all services. The bookstore calls this on behalf of the customer.

If it is specified for an order id, the order is attached to this and can’t be changed. There are some variations in the data you need to send in depending on what type of DRM the book

Technical API documentation: Orders and reporting

Downloading a product

The download service (/content) gives access to the end product based on an order placed in DDS. The process is the same for all kinds of content and delivery methods, but the client will need to handle the actual delivery different based on the format and delivery protocol (e.g. download of an EPUB vs. Streaming an Audio book over HLS). Which delivery methods used is based on the format of the file and the player-/reader application’s requirements.

Before a content can be delivered to the consumer DDS needs to do some processing to prepare the content for delivery (usually watermarking). As the size of files grows, this process can take more time than what is acceptable in a synchronous API call. Hence, DDS implements a redirect structure (using HTTP 302 redirects) where the first response to a download request redirects you to a status page (JSON), the status shows whether the content is ready for delivery. If status is true, then you can access the actual content using the link provided in the status page (actual content depends on format and delivery protocols, for e- /audio books you get the binary content of the file, for audio streaming you get the link to the streaming resource and for Adobe DRM books you will get the acsm file.)

Technical API documentation: Content download

 

Which types and bitrates are available for a particular audio book?

Bokbasen aims to provide a consistent set of types and bitrates for all books. However, the zip files split into multiple MP3 files is a special case and only available when the publisher delivers file that way. We also might introduce additional formats in the future if there is a need in the market.

The API provides a way of getting this information as a part of the download flow. If you initiate a GET content on an audio books distributed by Bokbasen and you either do not provide the type/bitrate parameter or that these are not a valid combination.

The JSON response will give you all available combinations of type and bitrate for the resource you requested and you can use that information to either resend the request with valid values or present this information to the user in a GUI to assure you are presenting options that are available.

Order Response Codes and Errors

In addition to HTTP status codes the service returns different messages as plain text.
It is important to note that these messages are only an indication of what is wrong, and that they may change in future versions of DDS if needed.
It is therefore important that the bookseller does not create solutions that make use of these error messages to something other than logging.
If you decide to build the flow in the application based on these text messages it is a risk that the solution will stop working in a future version of DDS services.

DDS Bokskya book feed

Introduction

In Bokskya (Cloud storage service) the consumer’s e-/audio books from all bookstores are put together in one shelf. A book is automatically linked to a consumers account when you place an order containing the consumer’s DDS-ID.

A bookseller is required to activate orders on all users.

The Bookshelf (represented by an OPDS-feed) is used to give the consumer access to download his books on any app or device that supports Bokskya. The store has access to fetching a customer’s OPDS-feed and deliver in an app, to a reading tablet or for download from the Bookstore (My Page).

In the OPDS-feed there are links to the REST interface to download all the consumer’s e- /audio books and references to fetch the cover image of the book.

It is strongly recommended to use the OPDS feed to get the URL needed to access the book, as this is will most likely:

  • Reduce number of errors

  • Make your application more resilient to changes in DDS

Services for fetching the users Bokskya feed with all purchased books

Bookshelf / OPDS - Documentation

Last-Modified and If-Modified-Since Headers

All responses from the /catalog/personal/ services that have a response code 200 OK also includes the Last-Modified response header.
See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.29 for more details. The services also accept and honour the If-Modified-Since header.

See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25 for more details.

NB! When using the If-Modified-Since header it is recommended that you use a date retrieved from the Last-Modified header of a previous request to the same service.
The reason for this is that the service expects that the parsed date retrieved from the If- Modified-Since-header is an exact match (with millisecond precision) to the date used in the Last-Modified header.


The service still respect and parses all the date-formats mentioned
in http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3.1 .

DDS Sales report

Introduction

The purpose of DDS Sales report is to inform the Bookstore of all transactions received by DDS. The bookstore can use the report to reconcile against the invoice from the publisher and their own system.
This API describes the file format and routine used for reporting e-/audio book sales back to the bookstore.

FTP Server

Every bookstore gets an FTP account dedicated for reporting FTP login is DDS Customer ID (look below)

Frequency

Reports are generated once a day. At 06:00 AM at the latest in the morning and put on DDS FTP Server. The report always contains all orders from the day before from 00:00:00 to 24:00:00.

Packing of reports

All reports generated are merged per customer per day. The files are placed in a zip file which contains an index. If there is nothing to report for one day the zip file will contain only the index file.

Price

Price is reported by the bookstore to DDS in the order API. DDS stores the price (along with the order id) and reports this back to the bookstore. Price is retail price excluding VAT. The price is used to calculate the price of the services Bokbasen bill their customers (publishers). This price should not be used as the basis for billing between publishers and bookstore.

Principles

The report is made per bookstore and the book owner (publisher). All reports to a bookstore are packed in a singe zip file.
Namin convetion for zip file is::
DDS_SalesReport_YYYYMMDD_<forlag customerid>_<bokhandel customerid>_<time_generated>.xml

(YYYYMMDD is the day the transactions occurred)

Reports (XML)

The reports are delivered in EDItX Sales Report 1.0 format. The complete format standard can be found here http://www.editeur.org/ . The fields used for reporting e-/audio book sales are shown below with explanation.

Orders and reporting

Security

  • Bokbasen services can only be accessed over HTTPS

  • It is the customer’s (using the API) responsibility to ensure safe storage of username and

    password to Bokbasen services

  • All calls from one partner should use a proxy when accessing these services and IP

    restrictions may be implemented

Watermarking

Audio

All files that are marked with SDRM (Social DRM) in the inventory service will be watermarked individually per transaction when the file is delivered through the get content API. Watermarking provides a social layer of security, where it is always possible to determine which transaction a file was bought if it is shared in a way not conforming to the licensing.

Ebooks

For ebooks, the watermark is a visible mark in the book where one can see the name provided displayed in a separate page of the book.

Integration for customers with partner agreement

This section describes functionality accessible solemnly to customer that has entered into a partner agreement with Bokbasen. The partner agreement is for customers that manages the technical delivery of the content to the consumer, and requires a completed security audit and specific agreement with Bokbasen. Contact us for further details.

Be advised that in order to be approved as a partner the security measures must be at the level that Bokbasen provides. All content delivered must therefore be applied watermarks containing the same level of information and be used in all channels, both downloads and streaming.

API documentation for Partner API endpoints is found here:

https://bokbasen.jira.com/wiki/display/api/Partner+models

There is only one end point that is exclusively available for partner customers, and that is a /raw version of GET content.

Get CONTENT/RAW

Please read the section “Downloading a product” to understand the download flow, this is the same for GET content and get content/raw. This section only explains the differences.

URL: /content/raw/{resid} Method: GET
Parameters: none Response on success: 302

Following the same download process as /content this will deliver either: - Single MP3 file in the best available quality

o Watermarked with signed in API user’s id

  • -  Raw EPUB files with no watermark

  • -  Raw EPB file with no watermark

    Note that the type parameter used in GET content is not needed for content/raw/. The resid that is needed is found in the “DDS Inventory”.

Process for downloading books as a partner

There are different “modes” of partners using the APIs differently to get access to raw files depending on their business needs. Two main approaches are recommended:

Partners keeping entire catalogue on their own servers

As part of your (at least) daily update from the inventory feed, we recommend you to store the version number of each book in your system. By doing that on each ISBN you can do a process similar to this

1. check if you have the book in your catalogue

  1. If no: initiate GET /content/raw/ with the <id> found in inventory (which is resid)

  2. If yes check if <inv:version> is different from the one in your system

    1. If yes: initiate GET /content/raw/ with the <id> found in inventory (which is resid)

    2. If no: skip to next entry

Note that this flow only describes how to find if there are new files available, you should also verify the access and published fields to see that the books are available to you.

Partners downloading raw files only after order is placed

These partners can initiate a GET /content/raw right after a successful order is placed. The resid and URI to /content/raw will be available in the personal OPDS feed, but if you already have the resource ID you can initiate the download directly.

Integration for customers using subscription models

When passing the agreed threshold for reading (i.e. 10%) the subscription provider should send a call this usage API reporting which book the threshold was met for. This can either be done in real time or on a batch basis, but reporting should at a minimum be done daily.

https://bokbasen.jira.com/wiki/display/api/Partner+models#Partnermodels- Revenuesharereporting

Related content