Posts Tagged ‘AtomPub’

Extending Atom: Thoughts on OPDS #2

Thursday, May 28th, 2009

First of all, Roger Sperberg wrote an excellent comment about the current OPDS draft:

With blogging, the Atom feed entry ought to include either a content child — containing the full blog post or a link to it (and the link relationship identified as ‘alternate’) — or a summary child whose content is an extract, abstract or short summary of one of the three types above.

If OPDS is a catalog of books, then there’s a mismatch between the blog model and the catalog model. The content in the catalog is material about a book, and the feed therefore ought to have the full material in content or a summary of it. A link child of contentshould take the feed’s consumer to that “full material.”

So maybe the catalog copy shouldn’t be likened to blog posts.

Then content could contain a link to the epub, and the catalog description would go into summary. Of course, the full descriptions in the catalog might be too long to use as intended in this type of feed.

In that case, just create a new type of relationship link, as was done in the examples for cover image and thumbnail, that describes whether this longer content is a synopsis, review or just longer description.

I agree with most of this comment. It makes more sense to use content for the EPUB file and summary for the description. We should also extend Atom rather than describe everything in XHTML: using DublinCore to describe the language, copyright status, publication date and other metadata.

Partial entry/Full entry

The current draft is full of new rel values, a design choice that we should avoid as much as possible (most of the time, a type and a rel value registered at the IANA link registry would be enough).

To support entries with longer content, as recommended by Roger Sperberg, we don’t need a new relationship link. In AtomPub:

Clients MUST NOT assume that an Atom Entry returned in the Feed is a full representation of an Entry Resource and SHOULD perform a GET on the URI of the Member Entry before editing it.

In the same RFC5023 for AtomPub, the “type” parameter was defined:

This specification defines a new “type” parameter for use with the “application/atom+xml” media type. The “type” parameter has a value of “entry” or “feed”.
Neither the parameter name nor its value are case sensitive.
The value “entry” indicates that the media type identifies an Atom Entry Document. The root element of the document MUST be atom:entry.
The value “feed” indicates that the media type identifies an Atom Feed Document. The root element of the document MUST be atom:feed.
If not specified, the type is assumed to be unspecified, requiring Atom processors to examine the root element to determine the type of Atom document.

Thanks to this type parameter, it’s fairly easy to point from a partial entry to a full entry using a link@rel="alternate"

<link rel="alternate" type="application/atom+xml;type=entry" href="..." />

For sources with a RDF document available (such as O’Reilly, and Feedbooks in the upcoming weeks), the same link@rel="alternate" could be used with application/rdf+xml.

Controlled vocabularies

The publication metadata required and allowed in OPF, should have the same status in OPDS.

Once the goals for OPDS are clearly defined (oops), we might extend this.

Any provider should be allowed to use additional extensions in their full entries.

Relationship to AtomPub

To allow such things as comments/reviews, OPDS could also support AtomPub.  With both the Atom Threading Extension and the current work on Collection Discovery, it should be fairly simple to support.

Tags: , ,
Posted in API | 5 Comments »

Hierarchy support for AtomPub

Monday, May 25th, 2009

Creating a powerful API for publishing is currently our top priority, and to improve our AtomPub service we recently added support for hierarchy in AtomPub.

Nikunj R. Mehta & Colm Divilly recently released 2 Internet-Drafts: one about collection discovery and the other one about hierarchy.

Internet-Drafts are still works in progress, but since the behavior for collection discovery was already described in a previous RFC, and the rel values used in the hierarchy draft are consistent with those registered at the IANA link registry, we decided to implement both of these drafts.

Collection discovery

Collections can be discovered in our feeds now (for example /book/id/contents.atom), and they’re not limited to the service document anymore. In the feed for a book you’ll find the following code:

<app:collection href="http://www.feedbooks.com/book/id/contents.atom">
  <app:accept>application/atom+xml;type=entry</app:accept>
  <title>Add new entries</title>
  <app:categories fixed="yes">
    <category term="Part"/>
    <category term="Chapter"/>
    <category term="Section"/>
    <category term="Text"/>
  </app:categories>
</app:collection>

Hierarchy

Hierarchy is supported through:

<link rel="down" ah:count="2" href="..."/>

ah:count is used to count the number of entries in the child feed, and in the child feed you’ll get a new collection to add new entries.

Tags: , ,
Posted in API | No Comments »

Publishing an e-book with Windows Live Writer

Tuesday, May 12th, 2009

Several e-books self-published on Feedbooks started as blogs (or blooks ?) first, such as Mortal Ghost or obnoxious librarian from hades.

Thanks to our new AtomPub service, it is now possible to use blog editing softwares such as Windows Live Writer (on Windows obviously) or MarsEdit (for Mac OS X) to publish new chapters of your book both on your blog and on Feedbooks.

First of all, you’ll have to create the book on Feedbooks. While you can manage the content of your book with these tools, they’re not capable of creating the book itself.

Once you’re done, just add a new blog account in Windows Live Writer, and select “Other” for the type of the blog.

Enter http://www.feedbooks.com as the URL of the blog along with your username/password. Windows Live Writer will automatically discover our AtomPub service and list your books. Select the right one and you can start publishing new items in your book !

As we continue to improve and extend our AtomPub service, expect more and more integration for Feedbooks into various publishing tools.

Tags: , ,
Posted in API | 6 Comments »

AtomPub on Feedbooks

Saturday, May 2nd, 2009

Atom Publishing Protocol

To allow any developer to interact with its publishing workflow, Feedbooks is releasing a new API based on the Atom Publishing Protocol standard. Based on the principles of a REST architecture, AtomPub is used by companies such as Google (GData), Microsoft (Live Framework) or Automattic (Wordpress) as a standard way to manipulate resources.

Implementation on Feedbooks

Currently, the AtomPub service on Feedbooks is strictly compliant with the standard, but to improve several things, it’ll be extended through Atom’s standard extension model in the near future:

  • Support for hierarchies will be added, probably using the following draft proposal.
  • Currently, for each item, we create a section in the book. We’ll extend AtomPub to specify if the item is a part, a chapter, a section or a simple text flow.
  • We don’t sort the order of the items in our feeds based on the last update, but based on the order of the items in the book. We’ll add this information in our items, and enable the possibility to re-order elements through AtomPub.

Service document

Our service document can be automatically discovered in any of our webpages through the link element with service as a value for its rel property.

To avoid long service documents, we use standard Atom pagination.

Collections/Items

A book can have several megabytes of text, and for this reason we don’t list the full content of each item in a collection but rely on GET requests on the item as recommended in the specs:

Clients MUST NOT assume that an Atom Entry returned in the Feed is a full representation of an Entry Resource and SHOULD perform a GET on the URI of the Member Entry before editing it.

What it means for publishing on Feedbooks

The main goal for this first release is to provide a service that’ll work with any AtomPub client. This way, the same software could both publish a post on a Wordrpress blog and a new section in a book on Feedbooks, without any additional work to support Feedbooks. While the next release will extend AtomPub to add things that are specific to books and publishing on Feedbooks, we’ll always be compatible with any AtomPub compliant client.

One of the first use for the API will be to make conversions from various formats easier. In our team, Benoît Larroque is currently working on a script to divide an HTML file and send it to Feedbooks through AtomPub. Such scripts will focus on properly dividing the text into parts/chapters/sections that the user can finetune afterwards in our Web UI.

Integration into other platforms such as blogs (Wordpress) or Wiki will be another focus, and dedicated desktop or mobile tools for publishing could also use this service.

But the main goal of course, is to provide a service that any developer can use to build innovative tools.

Tags: , ,
Posted in API | 3 Comments »