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.
- The resource should be served with the mime-type
- 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.
Top Level Fields
|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.|
|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
|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)|
<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>
- OPDS is based on Atom. A good primer is available at http://www.feedbooks.com/api/primer.
- The ID of an edition should *never* change as the Pugpig Readers will not know to remove the old versions.
- 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.
- Author currently not used by the Pugpig libraries
Last Modifieddate 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.