Application Programming Interface (API)

Comments

Contents

Overview

OPDS Primer

Comments

 

Related Links

OPDS Spec

Atom Format

AtomPub

Atom Threading Extensions

Comments are not part of the OPDS specifications.

For this reason, Feedbooks created an OPDS extension to list and post comments using Atom, AtomPub and a Link Relation registered at the Link Relation Registry.

Feedbooks uses the "replies" relation in Atom to identify comments, as defined in the Link Relation Registry: Identifies a resource that is a reply to the context of the link.

Such links can be found in either entries (for books) or feeds (for authors or lists).

Listing comments

Comments are listed as basic Atom entries. In atom:content the full comment is listed, and in atom:author you'll find the username of the author.

Posting a comment

In our feed for comments, you'll notice an app:collection element describing an AtomPub collection where you can POST an Atom entry.

The only element required in your Atom entry is atom:content, the rest will be added by the server when you POST it.

Authentication is required to post a comment.

A commande line example

First grab a book atom metadata

$ curl http://www.feedbooks.com/book/22.atom -i

HTTP/1.1 200 OK
Server: nginx/0.6.39
Date: Tue, 31 Aug 2010 10:09:46 GMT
Content-Type: application/atom+xml; charset=utf-8
Connection: keep-alive
Status: 200 OK
ETag: "2cc52deffd8068918e63e33d15a193e0"
X-Runtime: 1765
Content-Length: 3742
Set-Cookie: _sn=BAh7BjoPc2Vzc2lvbl9pZCIlYzU2OGFmYzQyNGRjYmE5NjYyMzIxOGEyOGQ1Y2FiNTA%3D--27bb72bd4d5a35538a77f036f54f2eaa7b9f3745; path=/; HttpOnly
Cache-Control: private, max-age=0, must-revalidate

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns:thr="http://purl.org/syndication/thread/1.0" xmlns="http://www.w3.org/2005/Atom" xmlns:dcterms="http://purl.org/dc/terms/">
<title>Alice's Adventures in Wonderland</title>
<id>http://www.feedbooks.com/book/22</id>
<author>
  <name>Lewis Carroll</name>
  <uri>http://www.feedbooks.com/author/13</uri>
</author>
<updated>2009-09-16T10:06:45Z</updated>
<dcterms:language>en</dcterms:language>
<dcterms:issued>1897</dcterms:issued>
<category term="FBFIC000000" label="Fiction"/>
<category term="FBJUV000000" label="Juvenile"/>
<category term="FBFIC009000" label="Fantasy"/>
<summary>Alice's Adventures in Wonderland (1865) is a novel written by English author Charles Lutwidge Dodgson, better known under the pseudonym Lewis Carroll. It tells the story of a girl named Alice who falls down a rabbit-hole into a fantasy world popul...</summary>
<dcterms:extent>26,432 words</dcterms:extent>
<dcterms:source>Wikisource</dcterms:source>
<link type="text/html" rel="alternate" href="http://www.feedbooks.com/book/22" title="View on Feedbooks"/>
<link type="application/epub+zip" rel="http://opds-spec.org/acquisition" href="http://www.feedbooks.com/book/22.epub"/>
<link type="application/x-mobipocket-ebook" rel="http://opds-spec.org/acquisition" href="http://www.feedbooks.com/book/22.mobi"/>
<link type="application/pdf" rel="http://opds-spec.org/acquisition" href="http://www.feedbooks.com/book/22.pdf"/>
<link type="image/jpeg" rel="http://opds-spec.org/image" href="http://www.feedbooks.com/book/22.jpg?t=1253095605"/>
<link type="image/jpeg" rel="http://opds-spec.org/image/thumbnail" href="http://www.feedbooks.com/book/22.jpg?size=thumbnail&amp;t=1253095605"/>
<link type="application/atom+xml" rel="related" href="http://www.feedbooks.com/author/13/books/top.atom" title="Other books from the same author"/>
<link type="application/atom+xml" rel="related" href="http://www.feedbooks.com/book/22/similar.atom" title="People also downloaded..."/>
<link type="application/atom+xml" rel="related" href="http://www.feedbooks.com/book/22/lists.atom" title="Reading lists for this book"/>
<link type="application/atom+xml" rel="related" href="http://www.feedbooks.com/book/22/categories.atom" title="Categories for this book"/>
<link type="application/atom+xml" rel="replies" thr:count="3" href="http://www.feedbooks.com/book/22/comments.atom" thr:updated="2010-06-09T07:07:18Z" title="Comments for this book (3)"/>
<link type="text/html" rel="replies" thr:count="3" href="http://www.feedbooks.com/book/22/comments" thr:updated="2010-06-09T07:07:18Z" title="Comments for this book (3)"/>
<link type="text/html" rel="related" href="http://www.goodreads.com/mobile/book/isbn/0785824464" title="View on Goodreads"/>
<content type="html">&lt;p&gt;Alice's Adventures in Wonderland (1865) is a novel written by English author Charles Lutwidge Dodgson, better known under the pseudonym Lewis Carroll. It tells the story of a girl named Alice who falls down a rabbit-hole into a fantasy world populated by peculiar and anthropomorphic creatures.
&lt;br /&gt;The tale is filled with allusions to Dodgson's friends (and enemies), and to the lessons that British schoolchildren were expected to memorize. The tale plays with logic in ways that have made the story of lasting popularity with adults as well as children. It is considered to be one of the most characteristic examples of the genre of literary nonsense, and its narrative course and structure has been enormously influential, mainly in the fantasy genre.&lt;/p&gt;</content>
  <link type="application/atom+xml" rel="contents" href="http://www.feedbooks.com/book/22/contents.atom"/>
</entry>

Now let's read the atom comments feed

$ curl http://www.feedbooks.com/book/22/comments.atom -i

HTTP/1.1 200 OK
Server: nginx/0.6.39
Date: Tue, 31 Aug 2010 10:12:05 GMT
Content-Type: application/atom+xml; charset=utf-8
Connection: keep-alive
Status: 200 OK
ETag: "1f7d352e57d07ace19b721beb245f9bf"
X-Runtime: 1167
Content-Length: 3867
Set-Cookie: _sn=BAh7BjoPc2Vzc2lvbl9pZCIlYjRmNjBmZGVlNDMwOTI3ZWMxYzNmYTU3MmZjMjlhMDk%3D--b0477c6c1ff7ea359fb6e814a52ad64428893371; path=/; HttpOnly
Cache-Control: private, max-age=0, must-revalidate

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:app="http://www.w3.org/2007/app" xmlns:opds="http://opds-spec.org/2010/catalog" xml:lang="en" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:thr="http://purl.org/syndication/thread/1.0" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.feedbooks.com/book/22/comments.atom</id>
  <link type="text/html" rel="alternate" href="http://www.feedbooks.com/book/22/comments"/>
  <link type="application/atom+xml" rel="self" href="http://www.feedbooks.com/book/22/comments.atom"/>
  <title>Comments for Alice's Adventures in Wonderland by Lewis Carroll | Feedbooks</title>
  <updated>2010-06-09T07:07:18Z</updated>
  <icon>http://www.feedbooks.com/favicon.ico</icon>
  <author>
    <name>Feedbooks</name>
    <uri>http://www.feedbooks.com</uri>
    <email>support@feedbooks.com</email>
  </author>
  <link type="application/atom+xml" rel="start" href="/catalog.atom" title="Home"/>
  <link type="application/opensearchdescription+xml" rel="search" href="/opensearch.xml" title="Search on Feedbooks"/>
  <link type="application/atom+xml" rel="http://opds-spec.org/shelf" href="https://www.feedbooks.com/user/bookshelf.atom" title="Bookshelf"/>
  <link type="application/atom+xml" rel="http://opds-spec.org/subscriptions" href="https://www.feedbooks.com/user/subscriptions.atom" title="Subscriptions"/>
  <link type="application/atom+xml" rel="http://opds-spec.org/sort/new" href="http://www.feedbooks.com/books/recent.atom" title="New Public Domain Books"/>
  <link type="application/atom+xml" rel="http://opds-spec.org/sort/popular" href="http://www.feedbooks.com/books/top.atom?range=month" title="Top Public Domain Books"/>
  <link type="application/atom+xml" rel="http://opds-spec.org/sort/new" href="http://www.feedbooks.com/userbooks/recent.atom" title="New Original Books"/>
  <link type="application/atom+xml" rel="http://opds-spec.org/sort/popular" href="http://www.feedbooks.com/userbooks/top.atom?range=month" title="Top Original Books"/>
<opensearch:totalResults>3</opensearch:totalResults>
<opensearch:itemsPerPage>20</opensearch:itemsPerPage>
<app:collection href="https://www.feedbooks.com/book/22/comments.atom">
  <app:accept>application/atom+xml;type=entry</app:accept>
  <title>Post a comment</title>
</app:collection>
<entry>
<title>A classic worth reading.  So many of the rhymes and stori...</title>
<id>http://www.feedbooks.com/book/22/comments#comment_1809</id>
<published>2010-06-09T07:07:18Z</published>
<author>
  <name>TinPigeon</name>
</author>
<content type="text">
A classic worth reading.  So many of the rhymes and stories have sound better in their original form.

I really with there was a free version with the illustrations!</content>
<updated>2010-06-09T07:07:18Z</updated>
</entry>
<entry>
<title>Very interesting book, though I imagine it's a lot more f...</title>
<id>http://www.feedbooks.com/book/22/comments#comment_1578</id>
<published>2010-04-03T00:29:35Z</published>
<author>
  <name>juliankay</name>
</author>
<content type="text">
Very interesting book, though I imagine it's a lot more fun to read to someone else.</content>
<updated>2010-04-03T00:29:35Z</updated>
</entry>
<entry>
<title>Good Read...  The movie leaves a lot of story out...  as ...</title>
<id>http://www.feedbooks.com/book/22/comments#comment_156</id>
<published>2008-07-11T23:30:04Z</published>
<author>
  <name>Viperengineer</name>
</author>
<content type="text">
Good Read...  The movie leaves a lot of story out...  as is true with most books gone to hollywood.  Never the less it was fun finally reading the &quot;real&quot; story.</content>
<updated>2008-07-11T23:30:04Z</updated>
</entry>
</feed>

Let's try to publish a comment. Do not forget to set the correct MIME type for the query or you will get an error.

$ curl https://www.feedbooks.com/book/22/comments.atom --data @- -H "Content-Type: application/atom+xml" -i
<entry xmlns="http://www.w3.org/2005/Atom" >
<title>A classic worth reading.  So many of the rhymes and stori...</title>
<id>comment 1 </id>
<content type="text">
Such a Nice book !
</content>
</entry>

HTTP/1.1 401 Unauthorized
Server: nginx/0.6.39
Date: Tue, 31 Aug 2010 10:36:17 GMT
Content-Type: text/html; charset=utf-8
Connection: keep-alive
Status: 401 Unauthorized
WWW-Authenticate: Basic realm="Document Realm"
X-OPDS-Register: https://www.feedbooks.com/user/register
X-Runtime: 294
Content-Length: 27
Set-Cookie: _sn=BAh7BjoPc2Vzc2lvbl9pZCIlMGQyZDI3OTQ1MjNiZDA4MmE0NTA1Zjk5OWViMzFjZjM%3D--412f1a0fd0c70ebb572a8bec17cc75add040cfd4; path=/; HttpOnly
Cache-Control: no-cache

HTTP Basic: Access denied.

With our credentials set :

$ curl https://www.feedbooks.com/book/22/comments.atom --data @- --user zeta1:test -H "Content-Type: application/atom+xml" -i 
<entry xmlns="http://www.w3.org/2005/Atom" >
<title>A classic worth reading.  So many of the rhymes and stori...</title>
<id>comment 1 </id>
<content type="text">
Such a Nice book !
</content>
</entry>

HTTP/1.1 201 Created
Server: nginx/0.6.39
Date: Tue, 31 Aug 2010 10:39:02 GMT
Content-Type: application/atom+xml; charset=utf-8
Connection: keep-alive
Status: 201 Created
Location: http://www.feedbooks.com/book/22/comments.atom#comment_1918
X-Runtime: 987
Content-Length: 330
Set-Cookie: id=10; domain=.feedbooks.com; path=/; expires=Thu, 30-Sep-2010 10:39:01 GMT
Set-Cookie: auth=b81dc6e934f2bca610041cf3538e8c339a6c7a60ceca0cabcd09bf1d8611; domain=.feedbooks.com; path=/; expires=Thu, 30-Sep-2010 10:39:01 GMT
Set-Cookie: _sn=BAh7CDoPc2Vzc2lvbl9pZCIlMzcxMDU5N2NlNzI3YzA0OTVjYjVmZDE5NTI1MjJhOTc6DHVzZXJfaWRpDyIKZmxhc2hJQzonQWN0aW9uQ29udHJvbGxlcjo6Rmxhc2g6OkZsYXNoSGFzaHsGOgtzaWduaW4wBjoKQHVzZWR7BjsIRg%3D%3D--571541f97ea2a9b5f8faeaa3fc21399465912730; path=/; HttpOnly
Cache-Control: no-cache

<entry xmlns="http://www.w3.org/2005/Atom">
<title>Such a Nice book !</title>
<id>http://www.feedbooks.com/book/22/comments#comment_1918</id>
<published>2010-08-31T10:39:02Z</published>
<author>
  <name>zeta1</name>
</author>
<content type="text">
Such a Nice book !</content>
<updated>2010-08-31T10:39:02Z</updated>
</entry>

The comment is now created !