Atom (RFC 4287) est l’un des formats XML qui permet d’avertir et de distribuer les mises à jour de votre site Web. Il a été conçu afin de réduire les ambiguïtés du format RSS 2.0. Après de longues batailles, les acteurs professionnels des outils traitant les flux RSS ont atteint un consensus à l’IETF en décembre 2005.

Si vous avez à choisir, nous vous encourageons à passer à Atom afin de rendre plus simple la maintenance ainsi que l’approche pour les utilisateurs.

Information sur le flux

Bien que le format ne soit pas nouveau, nous allons explorer comment concevoir un bon flux pour votre site Web tout en évitant quelques pièges courants. Cet article s’adresse donc aux gestionnaires de sites Web et aux développeurs de bibliothèques de code permettant de concevoir des flux.

Le format Atom est organisé selon deux axes majeurs :

• L’information à propos du flux lui même désignée par feed
• L’information à propos de chaque unité d’information désignée par entry

L’enveloppe fondamentale du flux sera ainsi un élément racine feed. Nous ajoutons l’espace de nom qui identifie le vocabulaire spécifique du format Atom. C’est une étiquette permettant aux outils extérieurs de bien identifier le vocabulaire.

<feed xmlns="http://www.w3.org/2005/Atom">
    …
</feed>

Il est possible également de définir la langue générale du flux en ajoutant un attribut de langue. Considérons que ce flux sera en français. L’attribut de langue pour le français est fr.

<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="fr">
    …
</feed>

Nous pouvons maintenant explorer les informations utiles et spécifiques à propos du flux.

UTF-8 pour le format et HTTP

Le flux est un format XML. Il est recommandé pour éviter tout problème de distribution dans la chaîne de traitement de fichiers XML de vous assurer que l’ensemble de votre flux soit codé en UTF-8.

Cela signifie également que vous preniez un soin particulier à servir le flux avec le Content-Type approprié.

Content-Type: application/atom+xml;charset=utf-8

L’identifiant unique du flux

Les flux de sites Web sont la plupart du temps mélangés avec de nombreux autres dans les lecteurs de flux ou les sites Web qui agrègent l’information. Il est alors important de définir un identifiant unique. Il existe quelques recettes pour définir un identifiant unique. J’utilise pour ma part le schéma d’URI tag: (RFC 4151). Dans le cas du site OpenWeb, j’adopterai le format suivant :

• le nom de domaine (celui du site permettant une unification précise)
• la date de création d’OpenWeb
• le mot blog pour identifier le flux du blog spécifiquement

Ce qui finalement donnera le tag suivant :

tag:openweb.eu.org,2003-03-22:blog

Une fois intégré au flux, nous obtenons :

<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="fr">
    <id>tag:openweb.eu.org,2003-03-22:blog</id>
    …
</feed>

Nous avons maintenant un flux qui peut être identifié uniquement au sein de nombreux autres flux. Nous pouvons imaginer que si nous avions un flux spécifique pour les commentaires, nous pourrions créer :

tag:openweb.eu.org,2003-03-22:blog-comment

afin de distinguer les deux id.

Le titre et sous-titre du Flux

Le titre du flux permet de donner un nom par défaut dans le lecteur de flux des lecteurs. Il est important qu’il soit plutôt court et facile à retenir pour les lecteurs afin de le retrouver au sein des autres flux. N’oubliez pas non plus que vous pouvez avoir plus d’un flux pour un seul site Web. Le sous-titre est bien souvent une phrase permettant de donner une accroche supplémentaire au site. Elle n’est pas toujours utilisée par les lecteurs de flux.

<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="fr">
    <id>tag:openweb.eu.org,2003-03-22:blog</id>
    <title>Collectif OpenWeb - Blog</title>
    <subtitle>Bien faire le Web</subtitle>
    …
</feed>

Si nous avions un flux de commentaires, nous pourrions par exemple avoir un titre légèrement différent :

 <title>Collectif OpenWeb - Commentaires du blog</title>

Auto-référence au flux

Lorsque le fichier XML est distribué et donc hors-contexte du site Web original, il est intéressant de permettre à un lecteur de connaître quelle est l’origine du flux. Ceci est fait en plaçant un élément link avec une relation self. Nous pourrions appeler cette fonction ET appelle maison.

<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="fr">
    <id>tag:openweb.eu.org,2003-03-22:blog</id>
    <title>Collectif OpenWeb - Blog</title>
    <subtitle>Bien faire le Web</subtitle>
    <link href="http://openweb.eu.org/feed.atom"
          rel="self"
          type="application/atom+xml" />
    …
</feed>

Identification de la page d’accueil

De même si votre site Web possède une page d’accueil pour l’information spécifique où se trouvent les dernières mises à jour, il est bon de pointer vers celle-ci. Un lecteur de flux pourra permettre à l’utilisateur de se rendre sur le site Web avec son navigateur.

<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="fr">
    <id>tag:openweb.eu.org,2003-03-22:blog</id>
    <title>Collectif OpenWeb - Blog</title>
    <subtitle>Bien faire le Web</subtitle>
    <link href="http://openweb.eu.org/feed.atom" rel="self" type="application/atom+xml" />
    <link href="http://openweb.eu.org/" rel="alternate" type="text/html" />
    …
</feed>

La date de dernière mise à jour

Cette information est importante car elle permet au lecteur de flux ou à l’agrégateur d’avoir une information supplémentaire sur la fraîcheur de l’information. Le format de la date est strict et doit absolument se situer dans le fuseau horaire Zulu (le temps universel - UTC), soit Z. À chaque fois, qu’une nouvelle entrée est créée et ajoutée au flux, il est nécessaire de mettre à jour la valeur de updated. Si par exemple, vous avez créé une nouvelle entrée le 1er mai à 13h34 (heure d’été), il est en fait le 1er mai 11h34 dans le fuseau Z.

<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="fr">
    <id>tag:openweb.eu.org,2003-03-22:blog</id>
    <title>Collectif OpenWeb - Blog</title>
    <subtitle>Bien faire le Web</subtitle>
    <link href="http://openweb.eu.org/feed.atom" rel="self" type="application/atom+xml" />
    <link href="http://openweb.eu.org/" rel="alternate" type="text/html" />
    <updated>2013-05-01T11:34:00Z</updated>
    …
</feed>

Il ne s’agit pas de donner l’heure du moment, mais bien l’heure de la dernière mise à jour du flux.

L’auteur du flux

Il peut-être utile d’avoir un point de contact pour l’auteur du flux ou l’éditeur du flux, que ce soit une organisation ou une personne individuelle.

<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="fr">
    <id>tag:openweb.eu.org,2003-03-22:blog</id>
    <title>Collectif OpenWeb - Blog</title>
    <subtitle>Bien faire le Web</subtitle>
    <link href="http://openweb.eu.org/feed.atom" rel="self" type="application/atom+xml" />
    <link href="http://openweb.eu.org/" rel="alternate" type="text/html" />
    <updated>2013-05-01T11:34:00Z</updated>
    <author>
        <name>Collectif OpenWeb</name>
        <uri>http://openweb.eu.org/</uri>
    </author>
    …
</feed>

La licence du contenu

Selon vos circonstances d’affaires et la façon dont vous préférez que vos contenus soient utilisés, vous pouvez indiquer une licence. Il sera possible de préciser la licence pour les contenus individuels. Le contenu des articles d’OpenWeb est sous licence CreativeCommons BY-SA

<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="fr">
    <id>tag:openweb.eu.org,2003-03-22:blog</id>
    <title>Collectif OpenWeb - Blog</title>
    <subtitle>Bien faire le Web</subtitle>
    <link href="http://openweb.eu.org/feed.atom" rel="self" type="application/atom+xml" />
    <link href="http://openweb.eu.org/" rel="alternate" type="text/html" />
    <updated>2013-05-01T11:34:00Z</updated>
    <author>
        <name>Collectif OpenWeb</name>
        <uri>http://openweb.eu.org/</uri>
    </author>
    <link href="http://creativecommons.org/licenses/by-sa/1.0/legalcode" rel="license" />
    …
</feed>

Voilà nous avons la structure de notre enveloppe et nous avons spécifié l’information générale à propos du flux, nous allons pouvoir passer aux informations individuelles.

Les entrées du flux

Le flux est composé d’une série d’entrées individuelles contenant une information particulière que nous allons détailler.

<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="fr">
    …
    <entry>…</entry>
    <entry>…</entry>
    <entry>…</entry>
    <entry>…</entry>
</feed>

L’identification unique de chaque billet de blog

Nous avons déjà vu comment créer un tag unique. Nous allons procéder de même cette fois ci pour les billets. Peu importe le système d’identification choisi, vous devez vous assurer que l’identificateur soit :

1. unique
2. stable (quels que soient les changements réalisés sur le billet)

Pour l’article récent Defining Breakpoints publié le 18 février 2013, nous pourrions par exemple, adopter la convention suivante :

<id>tag:openweb.eu.org,2013-02-18:defining-breakpoints</id>

• le nom de domaine
• la date de publication initiale (ne doit jamais changer)
• le chemin dans l’URI (ne doit jamais changer)

Si votre CMS et votre bibliothèque de code a un couplage entre l’URI et le titre du billet, c’est une mauvaise idée de composer son identifiant unique avec. Vous devez déterminer vous-même les éléments robustes pour composer votre identifiant stable et unique. La réflexion plus large sur la stabilité de vos URI dans votre site Web est une conséquence intéressante de ce choix.

<entry xml:lang="en">
    <id>tag:openweb.eu.org,2013-02-18:defining-breakpoints</id>
    …
 </entry>

Notez que cet article est en anglais alors que l’ensemble du flux est en français, nous le précisons.

Auto-référence vers le billet

De même que pour le flux, il peut être intéressant de fournir un lien vers le contenu original sur le site. Spécifiquement si vous décidez de créer un flux avec juste une partie du contenu. Cela permet aux lecteurs de demander au lecteur de flux de se rendre vers le contenu du site Web ou d’importer le reste du contenu.

<entry xml:lang="en">
    <id>tag:openweb.eu.org,2013-02-18:defining-breakpoints</id>
    <link rel="alternate" type="text/html"
          href="http://openweb.eu.org/articles/defining-breakpoints"/>
    …
 </entry>

Le titre du billet

Le titre de l’entrée est généralement le titre du billet dans votre gestionnaire de contenu. Cependant, si votre système crée des titres plutôt longs, il peut-être bon de trouver un bon titre pour le billet. Il n’est pas nécessaire d’inclure le titre du site Web puisqu’il est déjà disponible dans les informations générales de flux.

<entry xml:lang="en">
    <id>tag:openweb.eu.org,2013-02-18:defining-breakpoints</id>
    <link rel="alternate" type="text/html"
          href="http://openweb.eu.org/articles/defining-breakpoints"/>
    <title>Defining Breakpoints</title>
    …
</entry>

Date de publication et de mise à jour

Les dates ont le même format que pour la date générale du flux. Il existe essentiellement deux dates :

• la date de publication (immuable)
• la date de mise à jour

Une fois de plus, il est important de placer la date de publication dans le fuseau horaire de temps universel. Si vous avez publié et jamais mis à jour votre billet, les deux dates seront identiques.

<entry xml:lang="en">
    <id>tag:openweb.eu.org,2013-02-18:defining-breakpoints</id>
    <link rel="alternate" type="text/html"
          href="http://openweb.eu.org/articles/defining-breakpoints"/>
    <title>Defining Breakpoints</title>
    <published>2013-02-18T07:49:07Z</published>
    <updated>2013-02-18T13:45:58Z</updated>
    …
</entry>

Définir sa politique de mise à jour est une tâche intéressante. Il est possible de définir que chaque modification (correction typographique) doive faire l’objet d’une mise à jour de la date. Cependant ce n’est pas obligatoire, votre politique de mise à jour peut très bien se définir sur un changement de contenu significatif. À vous de mesurer l’enjeu de chaque choix.

Le contenu du billet

Atom permet trois formats distincts pour le contenu proprement dit de l’entrée :

• text
• html
• xhtml

Quel que soit le format choisi, c’est bien souvent l’endroit le plus fragile de votre flux. Il y a quelques règles essentielles à retenir pour que la paix des flux soit assurée.

1. Si votre flux est codé en UTF-8 (ce que nous recommandons), soyez sûr que le contenu du billet soit converti en UTF-8 avant de l’injecter dans votre flux.
2. Si vous choisissez text ou html, vous devez absolument convertir tous le contenu afin de neutraliser les caractères réservés, <, > et &.
3. Si vous choisissez xhtml, vous devez être absolument sûr que votre contenu est bien formé selon les règles XML. Il est bon généralement de passer par un interpréteur XML, car celui-ci produira une erreur en amont s’il y a un problème. Si vous n’êtes pas sûr de votre contenu, vous pouvez utiliser un processeur html5 pour traiter le contenu et le convertir en XML.
4. Si vous choisissez xhtml, il faut indiquer l’espace de nom XHTML afin de changer le modèle de contenu.
5. Transformer tous les liens relatifs en liens absolus. Les flux sont lus hors contexte du site Web.

Si vous respectez ces règles, vous allez vous épargner bien des soucis. Par exemple, dans le cas où le flux serait xhtml :

<entry xml:lang="en">
    <id>tag:openweb.eu.org,2013-02-18:defining-breakpoints</id>
    <link rel="alternate" type="text/html"
          href="http://openweb.eu.org/articles/defining-breakpoints"/>
    <title>Defining Breakpoints</title>
    <published>2013-02-18T07:49:07Z</published>
    <updated>2013-02-18T13:45:58Z</updated>
    <content type="xhtml">
        <div xmlns="http://www.w3.org/1999/xhtml">
        … ici le reste de votre contenu bien formé …
        </div>
    </content>
</entry>

Voilà, nous avons créé un flux au format Atom. Il y a de nombreuses autres propriétés utilisables afin d’être plus précis. Il est par exemple possible de spécifier les auteurs individuellement pour chaque entrée. Vous pouvez choisir de spécifier des licences différentes en fonction du contenu, etc.

L’art de HTTP et des mises à jour

Nous avons déjà vu qu’il était utile de servir le bon type de contenu pour le flux ainsi que d’indiquer le bon codage de caractères. HTTP est un protocole qui fonctionne sous forme de contrat entre le client et le serveur. Le client demande un statut à propos d’une ressource sur le Web, et le serveur donne une réponse en fonction des informations disponibles. L’en-tête HTTP Last-Modified permet de mieux régler les informations de cache. Nous avons déterminé précédemment que la dernière mise à jour sur le flux était :

<updated>2013-05-01T11:34:00Z</updated>

Ainsi les en-têtes HTTP doivent accompagner cette modification, en spécifiant par exemple :

Last-Modified: Wed, 1 May 2013 11:34:00 GMT

Attention, le format de date n’est pas le même que celui du flux, cependant le fuseau horaire est toujours GMT.

Validateur de flux Atom

Il existe deux validateurs de flux pour vous aider à comprendre les erreurs de votre flux. Un autre validateur très utile pour tout ce qui est relatif à HTTP peut vous permettre de découvrir les erreurs de vos en-têtes HTTP.

• Feed Validator
• W3C feed validator
• HTTP validator

Publiciser votre flux sur votre site Web

Finalement, il est important de permettre aux outils de découvrir votre flux lorsqu’ils passent sur votre site Web. Sur toutes les pages Web qui vous semblent utiles à cette publication, vous pouvez ajoutez dans le HTML une information pour découvrir le flux sous la forme :

<link rel="alternate"
      type="application/atom+xml"
      href="http://openweb.eu.org/feed.atom" />

Quelques liens pour aller plus loin

• Construction d’un fil RSS 1.0
• Introduction à la syndication de contenu avec RSS
• Syndication mon amour
• Indiquer la fréquence de mise à jour d’un fil de syndication au format RSS
• Atom sur wikipedia

Bon flux, bonne lecture.