...
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:
...
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
...
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.
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.
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 These services must be integrated in your user registration process, so that you ensure that all your user accounts have a corresponding Bokskya account.
...
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.
...
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?
...
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 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:
|
Services for fetching the users Bokskya feed with all purchased books
<Lenke til confluence dokumentasjon her>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. |
...
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 .
Service resources
DDS
...
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.
...
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.
...
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?>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
...
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
...