Follow

Document Discovery (OPDS feed)

Overview

This is the API entry point, and it provides the list of all editions (or issues or publications) available to the Pugpig reader. It uses the Open Publication Distribution System (OPDS) Catalog specification.

General

  • The resource should be served with the mime-type application/atom+xml
  • The resource is requested every time a client is started, so should be cached
  • The resource should be publicly available

Testing and Validation

  • Feeds should validate using the Unofficial OPDS validator.
  • Feeds should validate using the W3C Feed Validator, although there will be warnings regarding the OPDS namespace and the fact we do not mandate URIs for the Atom IDs.

Deleting Items from the Feed

From Pugpig 1.9 and later, the clients support deletedEntry ATOM (Tombstones) (http://tools.ietf.org/html/rfc6721) in the feeds to indicate that an item has been deleted. Without these, a client will never “forget” an edition that it has seen.

Fields

Top Level Fields

PropertyOccursTypeDescription
atom:id 1 Tag URI Universal Unique Identifier of the OPDS feed. Not used by the Pugpig client but required by ATOM.
atom:link (rel=“self” type=“application/atom+xml;profile=opds-catalog;kind=acquisition”) 1 URI This URL to this document.
atom:title 1 Text Title of the feed. Not used by Pugpig currently.
atom:subtititle 1 Text Subtitle of the edition. Not used by Pugpig currently.
atom:author 0..1 Atom Author The author of the items in this feed (if all by the same author). Pugpig currently only reads the author on the entries
atom:updated 1 Timestamp Time when this contents of the feed was last significant updated. Should be the max updated date of the entries. Not used by Pugpig clients.
atom:entry 0..n Atom Entry An entry for each edition/publication in the feed.

Entry Fields

PropertyOccursTypeDescription
atom:id 1 Tag URI Universal Unique Identifier of the edition. This should never change once published. Currently this needs to match the iTunes Connect edition In App ID if using In App purchases.
atom:link (rel=“http://opds-spec.org/image” type=“variable”) 1 URI A link to the cover image for the edition. Recommended 4:3 aspect ratio. The type should be one of image/png, image/jpeg, image/jpg or image/gif.
atom:link (rel=“http://opds-spec.org/acquisition” type=“variable”) 0..1 URI A link to the contents of the edition. Should be used for free editions only. Multiple formats are supported - see table below. The type should match the MIME type of the chosen format.
atom:link (rel=“http://opds-spec.org/acquisition/buy” type=“variable”) 0..1 URI This link is the same as the acquisition link, but should be used if the edition is not free. An opds:price element should be included inside this element, although the current iTunes integration fetches the price from the App Store.
atom:link (rel=“alternate” type=“xxxx”) 0..1 URI We recommend this be the same as the acquisition or acquisition/buy link. Not used by Pugpig client.
atom:title 1 Text Title of the edition.
atom:summary 0..1 Text Summary of the edition - not required although Atom recommends it.
atom:author 1 * Atom Author The author of this item. Required unless the top level feed has an author.
dcterms:issued 0..1 Granular date The date of the edition, with a granularity matching frequency of publication. For example, a monthly would have YYYY-MM, while dail or weekly YYYY-MM-DD. Used to order issues. Strongly recommended for Pugpig.
atom:updated 1 Timestamp Time when this edition was last significant updated. Used for caching.
atom:published 0..1 Timestamp Time when this edition was first published. Used as fallback if dcterms:issued not supplied
app:control 0..1 App Control Element Flag an edition as draft

Acquisition Link Options

http://opds-spec.org/acquisition or http://opds-spec.org/acquisition/buy links should be one of these:

PropertyOccursTypeDescription
atom:link (rel=“http://opds-spec.org/acquisition” type=“text/cache-manifest”) 1 URI Edition contents contained in a simple text format as defined in HTML Manifest Document Type
atom:link (rel=“http://opds-spec.org/acquisition” type=“application/atom+xml”) 1 URI Edition contents contained in an Atom feed as defined inAtom Document Type
atom:link (rel=“http://opds-spec.org/acquisition” type=“application/pugpigpkg+xml”) 1 URI Edition contents contained in a set of ZIP files as defined inPackage Document Type
atom:link (rel=“http://opds-spec.org/acquisition” type=“application/opf”) 1 URI This should link to the .opf file of an unzipped ePub as defined in OPF Document Type.
atom:link (rel=“http://opds-spec.org/acquisition” type=“application/epub”) 1 URI This should link to a zipped .epub file ePub Document Type.
atom:link (rel=“http://opds-spec.org/acquisition” type=“application/octet-stream”)  1  URI Only supported in Pugpig Products. This should link to an asset which your app can interpret as it sees fit (e.g. a PDF)

Example

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:opds="http://opds-spec.org/2010/catalog">
<id>pugpig-editions</id>
<title>PugpigEditions</title>
<updated>2014-01-01T00:00:00Z</updated>
<author>
<name>Bob Smith</name>
</author>
<entry>
<title>Edition 01</title>
<id>com.pugpig.edition01</id>
<updated>2014-01-01T00:00:00Z</updated>
<dcterms:issued>2013-09-01</dcterms:issued>
<author>
<summary />
<link rel="http://opds-spec.org/image" type="image/jpg" href="images/cover.jpg" />
<link rel="http://opds-spec.org/acquisition" type="application/atom+xml" href="atom.xml" />
<link rel="alternate" type="application/atom+xml" href="atom.xml" />
</entry>

Notes

  1. OPDS is based on Atom. A good primer is available at http://www.feedbooks.com/api/primer.
  2. The ID of an edition should *never* change as the Pugpig Readers will not know to remove the old versions.
  3. As the Pugpig Readers only take a single OPDS entry point, other factors (such as IP address) can be used to decide whether to show draft editions. Special care needs to be taken when these are cached upstream - the internal feeds should never be cached anywhere.
  4. Author currently not used by the Pugpig libraries
  5. The Last Modified date in the header is the same as the top level <updated> date. This is equal to the later of when an edition is packaged or it's meta data edited. The <updated> date in the edition <entry> is equal to the latest package date for a normal OPDS feed and the latest modified data for an atom feed.
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk