Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.

...

Services to create and administrate user accounts and authorize reading devices and applications.

Overview of Users Books - Bokskya Bookshelf

...

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 to three types of DRM:

  • Adobe Content Server 4 (TDRM) - being phaced out

  • Watermarking (SDRM)

  • Readium LCP

About formats

Bokbasen supports the following audio book formats:

...

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.

...

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

Note

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

...

  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:

...

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

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

Authentication Service (upcoming)

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

...

  • 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.

...

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 id 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: https: //bokbasen.jira.com/wiki/display/api/Orders 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.

...

Technical API documentation: https://bokbasen.jira.com/wiki/display/api/Content + download

...

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

...

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.

Info

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.

Info

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

...

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

Note

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 .

...

  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

Info

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

...