L'API Feedbooks

Présentation

Contents

Overview

OPDS Primer

Comments

 

Autres liens

Spécification OPDS

Format Atom

AtomPub

Web Linking

Feedbooks est ouvert aux développeurs tiers via une Application Programming Interface (API), basée sur les principes du style d'architecture Representational State Transfer (REST).

Dans sa version actuelle, l'API est principalement orientée vers la lecture d'information, à l'exception de nos services de publications et de commentaires.

RESTful

Feedbooks est à la tête du projet OPDS, dont l'objectif est de standardiser la distributions de ressources culturelles dématérialisées. La quasi intégralité de notre API s'appuie sur cette variante d'Atom.

OPDS suite la contrainte HATEOAS du style d'architecture REST, ce qui signifie que toutes les interactions sont décrites via des types MIME, des relations et des liens. C'est la principale raison pour laquelle nous ne documentons pas de resources en particulier, et conseillons aux applications de ne pas s'appuyer sur une URI précise pour interagir avec notre service.

Nous vous recommandons de suivre le groupe OPDS, étant donné que ce standard va continuer d'évoluer dans les prochaines années.

En plus de la spécification OPDS nous publions aussi une introduction à OPDS afin d'en comprendre les concepts fondamentaux.

Utilisation

Nous ne demandons pas aux développeurs d'enregistrer leur application ou d'utiliser la moindre clé pour interagir avec notre API, mais il y a un certain nmbre de règles que nous demandons de suivre :

Ressources

L'adresse de notre catalogue est http://www.feedbooks.com/catalog.atom

La plupart de nos URIs acceptent à la fois le format XHTML ainsi que le format Atom: indiquez le format dans le Accept header.

Toutes nos ressources sont découvrables en partant de l'adresse princiale du catalogue.

Nous déconseillons d'inclure des resources spécifiques de notre catalogue via leur URI, à l'exception de l'adresse du catalogue principal.

A la place, naviguez dans nos ressources en vous appuyant sur le type MIME et les relations indiquées dans nos liens.

Encodage

Feedbooks s'appuie exclusivement sur UTF-8.

Authentification

Certaines ressources sur Feedbooks demandent de s'authentifier, alors que d'autres permettent d'accèder à des informations supplémentaires si l'on est authentifié (par exemple, être authentifié au moment d'un téléchargement ajoutera ce livre à votre bibliothèque).

Feedbooks s'appuie sur Basic Auth et HTTPS à cette fin.

Auto-découverte

Nos resources sont découvrables de plusieurs manières : par exemple dans nos pages XHTML, nous indiquons des liens dans la section header.

En vous appuyant sur le type MIME et la relation, vous pouvez en déduire la nature de la ressource.

Nous ne définissons pas de nouvelles relations, et nous nous appuyons exclusivement sur celles définies dans Web Linking et la spécification OPDS.

Langue

Sur certaines de nous ressources, nous nous appyons sur le header Accept-Language afin de filtrer le contenu affiché.

Certains éléments sont aussi traduits en s'appuyant sur ce même header.

Par défaut, tout est affiché en Anglais, si aucune valeur n'est indiquée dans ce header.

Feedbooks supporte 5 langues : anglais, français, espagnol, allemand et italien.

Cache côté client

Feedbooks s'appuie sur du cache HTTP pour optimiser la qualité de service à travers notre API.

Nous recommandons de vous appuyer sur les ETags présents dans nos headers afin d'éviter des requêtes inutiles.

Pour nos ressources statiques, nous nous appuyons aussi sur le header Cache-Control.

Compression

Un support Gzip est disponible sur l'ensemble de nos ressources OPDS.