...
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 API 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
...
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. A separate contract concerning metadata is necessary. 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.
...
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
...
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.
| Note |
|---|
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.
...
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)
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)
EBP (E-book plus which is a proprietary HTML5 based format packed in a zip)
The process for getting the download link is the same for all formats, but you need to implement support for the specific formats in your reader/player.
About the format EBP
This format can only be downloaded to and read in custom made apps.
The store has the following possibilities; to create an app that supports the format, to inform the customer about the apps on the market that support the format or not offer these e-books at all.
The format is not delivered with DRM. Any copy protection mechanisms must be built into the app.
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.
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.
...
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.
| 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
...
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 , EBP etc.)
Make a query to DDS Inventory REST API
Display metadata for all e-/audio books with published status = true combined with
access = true
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.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 https://bokbasen.jira.com/wiki/display/api/Authentication+Service
Login and Authorization
A distributor will be assigned a username and password when created. The username and password is used against the authentication service to create a token, this token (referred to as TGT) is then used against all other service calls to DDS. The token has a limited validity (2 hours) so the implementation must re-create the token on a regular basis.
To create a token use the POST call to the service, you can also actively logout and make the token invalid by using the DELETE call to the service.
(Lenke til dokumentasjonen )
Example usage
HTTP Header Authentication
All REST service calls to DDS have to be authenticated using the TGT-token from the authentication service. In addition, you need to include a date header, with the current time in GMT using a date format following RFC 1123.
Note that in addition to the token (TGT-*) you received from the authentication service, you need the static name “Boknett” in the header. Your Date header should be current on every request, and the request will fail if there is more than a 15 minutes difference in the Date header and the Bokbasen server clock. Bokbasen recommend that your server is using a NTP service to assure synched times.
<Lenke til dokumentasjonen>
DDS Inventory
Introduction
Skrive litt her om inventory og lenke til confluence siden.
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.
All IDM services are available under a separate domain: idp.dds.boknett.no (production) and idp.dds.boknett.webbe.no (test). Access to these services uses the same authentication as the order services described in this document (see “Login and Authorization” section).
These services should 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.
<Lenke til confluence>
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 id 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
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: https://bokbasen.jira.com/wiki/display/api/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.
<Lenke til confluence dokumentasjon her>
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 that are registered if using the Bokskya Feed. It is not allowed to just get the Bokskya Feed and not activate new or
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.
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.
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.
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.
| 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:
|
...
Make your application more resilient to changes in DDS
Services for fetching the users Bokskya feed with all purchased books
<Lenke til confluence dokumentasjon her>
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
...
|
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-sec3sec14.html#sec3.3.1html#sec14.25 for more details.
Service resources
DDS REST Services
IDM REST Services
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)
<MÅ oppdateres?>
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.
<Må oppdateres?>
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.
<Lenke til confluence side med dokumentasjon her?>
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.
Although they serve the same purpose, technically watermarking is quite different for audio- and e-books.
For audio books Bokbasen use an external party to implement watermarks. http://AudioLock.NET Ltd has an algorithm for watermarking that is a 'strict watermarking' technique which means that the watermark cannot be detected or decoded without the original audio.
...
| 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 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.
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.
...
If no: initiate GET /content/raw/ with the <id> found in inventory (which is resid)
If yes check if <inv:version> is different from the one in your system
If yes: initiate GET /content/raw/ with the <id> found in inventory (which is resid)
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
...