Understanding Acquisition Links

OPDS is all about links: that's how we define where a user can browse, search and acquire publications.

Every publication available in an OPDS catalog is required to have at least one acquisition link with:

• a rel attribute, which indicates the type of acquisition that a client can expect
• a type attribute, which indicates the format of the publication

The following rel values are available:

• http://opds-spec.org/acquisition/open-access for Open Access publications
• http://opds-spec.org/acquisition/buy for publications that you can buy
• http://opds-spec.org/acquisition/borrow for publications that you can borrow
• http://opds-spec.org/acquisition/subscribe for publications that you can subscribe to
• http://opds-spec.org/acquisition/sample to sample a publication
• http://opds-spec.org/acquisition when none of the other values are appropriate or you don't have additional information

In the spec we offer the following example:

<link rel="http://opds-spec.org/acquisition" 
      type="video/mp4v-es" 
      href="/content/free/4561.mp4"/>

If the same publication is available in multiple formats as unique resources, they would simply be listed using multiple acquisition links in the same entry:

<link rel="http://opds-spec.org/acquisition/borrow" 
      href="/content/borrow/4561.mobi"
      type="application/x-mobipocket-ebook"/>
 
<link rel="http://opds-spec.org/acquisition/borrow" 
      href="/content/borrow/4561.epub"
      type="application/epub+zip"/>

Price element

If the publication requires payment, at least one opds:price element is required, where the value is the price and the currencycode attribute indicates the currency:

<link rel="http://opds-spec.org/acquisition/buy"
      href="/product/song1.mp3"
      type="audio/mpeg">
  <opds:price currencycode="USD">1.99</opds:price> 
</link>

The price element can only be used with the following rel values:

• http://opds-spec.org/acquisition/buy
• http://opds-spec.org/acquisition/subscription
• http://opds-spec.org/acquisition/sample

Indirect Acquisition

In certain cases, the acquisition link doesn't point directly to the publication.

This could be the case for example with a bundle, where a zip file is distributed with the same publication available in different formats inside.

In this case, an opds:indirectAcquisition element is required, where the type attribute is the media type:

<link type="application/zip" rel="http://opds-spec.org/acquisition/open-access" href="/item/1111/buy/">
  <opds:indirectAcquisition type="application/epub+zip" />
  <opds:indirectAcquisition type="application/pdf" />
  <opds:indirectAcquisition type="application/x-mobipocket-ebook" />
</link>

This could also be the case of a DRM format, such as ACS4 for EPUB & PDF, where the client acquires the final publication through an ACSM file:

<link type="application/vnd.adobe.adept+xml" rel="http://opds-spec.org/acquisition/buy" href="/item/4141/buy">
  <opds:price currencycode="USD">4.29</opds:price>
  <opds:indirectAcquisition type="application/epub+zip" />
</link>

Aside from container formats, indirect acquisition is also widely used to handle a transaction in the browser. In this case, the atom:link points to a webpage, while the opds:indirectAcquisition element indicates the format that the client can expect to acquire at the end of the transaction:

<link type="text/html" rel="http://opds-spec.org/acquisition/buy" href="/item/4141/buy">
  <opds:price currencycode="USD">4.29</opds:price>
  <opds:indirectAcquisition type="application/vnd.adobe.adept+xml">
    <opds:indirectAcquisition type="application/epub+zip" />
  </opds:indirectAcquisition>
</link>

Filtering publications

OPDS clients can filter publications based on these acquisition links and opds:indirectAcquisition elements and decide to display only a subset or even none of the publications if they consider that they can't open them or deal with the workflow described.