Bookshelf / OPDS

1 Get OPDS
- 1.1 Performance considerations
- 1.2 OPDS format
  - 1.2.1 Example 1 - EPUB ebook
  - 1.2.2 Example 2 - Excerpt of EPUB ebook
  - 1.2.3 Example 3 - Audio book

This service provides access to each Bokskya's end user's bookshelf.

New Authentication & URLs introduced Q2 2024

Get OPDS

Get personal bookshelf for DDS user in OPDS XML format.

URL	`https://api.bokbasen.io/bokskya/content/v1/{id}` `https://api.dds.boknett.no/catalog/personal/{ddsId}` The token acquired from the Authentication Service. Example: `Authorization: Boknett TGT-....` Required header: `Date` The timestamp the request was made. Must comply with RFC 1123 date formats. Example: `Tue, 10 Jun 2014 16:23:42 GMT`
Method	`GET`
Request headers	`Authorization`	Required	See Authentication Service Audience: `https://api.bokbasen.io/bokskya/`
	`If-Modified-Since`	Optional	Used for client caching of feed. See chapter on performance considerations below. See RFC for details.
Response body on success	XML OPDS feed (See below) or empty body if using "If-Modified-Since" and response is 304.
Response headers	`Last-Modified`	Date header showing last time this user's OPDS feed was updated (see RFC for details). Use this date in "If-Modified-Since" when doing your subsequent request.
Returns	`200`	OK
	`304`	Not modified
	`40x`	On error

Performance considerations

As these data for many users do not change very often, this is a strong candidate for client caching. The API provides specific functionality for this, and we highly recommend you to implement caching of the feeds on the client side to improve consumers user experience.

To support client caching in a efficient way the end point support the If-Modified-Since HTTP header, allowing for a quick way of checking if there has been any changes from last time the feed was loaded. When doing a request with this header, you will either receive a 200 OK with a body (meaning there was a changes since last time) or a 304 Not Modified with an empty body (meaning there was not change, so you should go ahead and used you cached version).

Technical details can be found here:

Last-Modified response header: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.29
If-Modified-Since header: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25

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 .

OPDS format

The OPDS format is a specification based on the ATOM feed standard. Each book in the bookshelf is represented as an <entry> element with basic metadata and links to download and cover images. Below are some examples on the typical different types of entries. Note that Bokbasen is using some features from the not yet released version 1.2 in order to support audio books, so validating against the current XSD will not work.

Basic metadata is provided in the OPDS feed for showing simple information about the book, but this is not a metadata service, use Bokbasen's Metadata Export Service to get the latest and most accurate Metadata information.

Example 1 - EPUB ebook

<entry>
	<title>Anna Karenina</title> <!-- Title of the book -->
	<link rel="http://opds-spec.org/image/thumbnail" type="image/jpeg" 
	      href="https://media.boknett.no/objects/07/34/50113407/appcover_OB_affaecfac708e5380b0cd279c2abc3f0bb8b9f79.jpg"/> <!-- Link to cover image -->
	<link rel="http://opds-spec.org/acquisition/open-access" 
	      type="application/json" 
	      href="https://api.dds.boknett.no/content/4c97596d-d03b-4b79-b133-cbaea8a00c1b">
		<opds:indirectAcquisition type="application/epub+zip"/>
	</link> <!-- Link to GET content API for downloading book, opds:indirectAcquisition type has the mime type of the download -->
	<author>
		<name>Tolstoj, Leo</name>
	</author>
	<id>37866ca4-2614-4ec1-9d73-c14d6cbfc12b</id> <!-- Resource-id of the book, note that resource ids change if new version is published -->
	<created>2015-08-17T13:41:46.000Z</created>
	<updated>2015-02-11T12:36:52.000Z</updated>
	<dc:identifier xsi:type="dcterms:URI">urn:uuid:37866ca4-2614-4ec1-9d73-c14d6cbfc12b</dc:identifier> <!-- Resource-id in DC, same as above -->
	<dc:identifier xsi:type="dcterms:URI">urn:isbn:9788201000654</dc:identifier>
	<dc:publisher>Testforlaget</dc:publisher> 
	<dc:issued>2010</dc:issued>
	<dc:language>bm</dc:language>
</entry>

Example 2 - Excerpt of EPUB ebook

<entry>
   <title>Blod på snø</title>
   <link rel="http://opds-spec.org/image/thumbnail" 
         type="image/jpeg" 
         href="https://media.boknett.no/objects/40/95/150169540/appcover_OB_a0978d82ad8e88d5158305b9ac99bdf885f2e3cb.jpg" />
	<!-- This is deprecated and should not be used for excerpts, just kept for backward compatibility for now. Excerpts should only have rel="http://opds-spec.org/acquisition/sample"  -->
   <link rel="http://opds-spec.org/acquisition/open-access" 
         type="application/json" 
         href="https://api.dds.boknett.no/content/5c736f58-9e18-45df-bb0a-00b5c4cc16d7">
     <opds:indirectAcquisition type="application/epub+zip" />
   </link>
	<!-- Below you can see that this is a sample based on the rel="" attribute -->
   <link rel="http://opds-spec.org/acquisition/sample" 
         type="application/json" 
         href="https://api.dds.boknett.no/content/5c7f6f58-9e18-45df-bb0a-00b5c4cc16d7">
     <opds:indirectAcquisition type="application/epub+zip" />
   </link> 
   <author>
     <name>Nesbø, Jo</name>
   </author>
   <id>1759c8af-6f3c-4177-b5ba-d42ebc21103f</id>
   <created>2015-04-30T19:21:17.000Z</created>
   <updated>2015-03-03T23:00:03.000Z</updated>
   <dc:identifier xsi:type="dcterms:URI">urn:uuid:1759c8af-6f3c-4177-b5ba-d42ebc21103f</dc:identifier>
   <dc:identifier xsi:type="dcterms:URI">urn:isbn:9788203359149</dc:identifier>
   <dc:publisher>Aschehoug</dc:publisher>
   <dc:issued>2015</dc:issued>
   <dc:language>bm</dc:language>
</entry>

Example 3 - Audio book

<entry>
    <title>Kvelande kjærleik</title>
    <link rel="http://opds-spec.org/image/thumbnail" 
          type="image/jpeg" 
          href="https://media.boknett.webbe.no/objects/44/56/150295644/productimage_M1_0661d5f330a34416e489bd31f2784ea98eefa5a1.jpg" />
    <link rel="http://opds-spec.org/acquisition/open-access" 
          type="application/json" 
          href="https://api.dds.boknett.webbe.no/content/1cff633c-3660-4a7d-a9c6-c8bf1e6ed15f">
      <opds:indirectAcquisition type="audio/vnd.bokbasen.progressive-private" opds:bitrate="64" />
      <opds:indirectAcquisition type="audio/vnd.bokbasen.zipped-private" opds:bitrate="64" />
      <opds:indirectAcquisition type="audio/vnd.bokbasen.complete-private" opds:bitrate="64" />
      <opds:indirectAcquisition type="audio/vnd.bokbasen.complete-public" opds:bitrate="64" />
      <opds:indirectAcquisition type="audio/vnd.bokbasen.hls-private" opds:bitrate="64" />
      <opds:indirectAcquisition type="audio/vnd.bokbasen.zipped-public" opds:bitrate="64" />
    </link>
    <author>
      <name>Ferrante, Elena</name>
    </author>
    <id>8065f2cc-5c6d-4c38-98be-23832a33f780</id>
    <created>2018-09-12T06:27:42.000Z</created>
    <updated>2018-07-02T13:15:37.000Z</updated>
    <dc:identifier xsi:type="dcterms:URI">urn:uuid:8065f2cc-5c6d-4c38-98be-23832a33f780</dc:identifier>
    <dc:identifier xsi:type="dcterms:URI">urn:isbn:9788252197266</dc:identifier>
    <dc:publisher>Samlaget</dc:publisher>
    <dc:issued>2018</dc:issued>
    <dc:language>nob</dc:language>
  </entry>