API for Feedbooks

Overview

Contents

Overview

OPDS Primer

Comments

 

Related Links

OPDS Spec

Atom Format

AtomPub

Web Linking

Feedbooks is open to third party developpers via an Application Programming Interface (API), based on the principle of the Representational State Transfer (REST) architectural style.

In its current version, the API is read mostly, aside from the publishing service and comments in AtomPub.

RESTful

To distribute content, Feedbooks is a participant in the OPDS effort. Therefore most of our resources are in this particular flavor of Atom.

OPDS follows the HATEOAS constraint from the REST architectural style, which means that everything is designed around media types, links and link relationships. That's why we don't document particular resources (we don't need to), and strongly recommend against hardcoding any specific URI at Feedbooks aside from the main OPDS catalog.

We highly recommend following the OPDS group, as this standard will continue to evolve beyond the current specification.

Aside from the OPDS Spec we also provide an OPDS Primer in order to understand the key concepts associated to this standard.

Fair Use

We don't ask developpers to register their applications and use any sort of key to interact with our API, but there are a few rules that we ask you to follow:

Resources

You'll find our main catalog at http://www.feedbooks.com/catalog.atom

Most of our URIs accept both XHTML and Atom: try sending a different Accept header.

You can discover all of our OPDS resources while navigating our catalog and starting from our main catalog.

We recommend against hard-coding any of our URIs in your application, aside from the main OPDS catalog.

Instead, follow links based on relationships and mimetypes to access the right URI.

Encoding

All requests and answers on Feedbooks are in UTF-8. If you're using parameters (which you shouldn't, follow the links instead), remember to correctly encode your URI.

Authentication

Some resources on Feedbooks require to be authenticated, while some other might provide additional features if you're authenticated (for example, sending your credentials while requesting a download will log your download).

Always use HTTPS when sending credentials.

Auto-discovery

To auto-discover our resources, we use links in the head of our XHTML pages and in our OPDS feeds.

Based on the type and rel value, you can guess the nature of the link.

We do not define new rel values and strictly use rel values defined in the Web Linking RFC or the OPDS spec.

Language

On some of our resources, we filter the content displayed based on the Accept-Language header.

Some elements are also localized using the same language specified in your headers.

If the language is not defined or if we don't use the language defined in this header, we automatically use English as the default language.

We include a Vary: Accept-Language header to indicate that the content is affected by the use of the Accept-Language header.

Feedbooks currently support five languages: English, French, Spanish, German and Italian.

Client Side Caching

Feedbooks relies heavily on HTTP caching to optimize the quality of service throughout the API.

We highly recommend using the ETags specified in our HTTP headers to avoid duplicate requests that are unecessary.

For our static resources we also use the Cache-Control header.

In a mobile environment, you should absolutely use these headers.

Compression

GZip support is available to speed things up.