Ce document est une traduction du document RFC 5023 de l'IETF (Internet Engineering Task Force) ;
il peut comporter des erreurs ou en introduire de nouvelles. Seul fait référence l'original disponible à
ftp://ftp.rfc-editor.org/in-notes/rfc5023.txt.
La traduction est proposée sous licence Creative Commons.
Date de publication : 5 août 2008.
Network Working Group J. Gregorio, Ed. Document RFC : 5023 (errata) Google Categorie : Standards Track B. de hOra, Ed. NewBay Software Octobre 2007
Ce document définit un protocole du circuit des standards Internet de la communauté Internet, et il appelle le débat et des suggestions d'amélioration. Veuillez consulter l'édition courante du document Internet Official Protocol Standards (STD 1) pour l'état de standardisation et le statut de ce protocole. La distribution de ce mémoire est libre.
Le protocole de publication Atom (AtomPub) est un protocole de niveau supérieur (application-level protocol) pour la publication et l'édition de ressources web. Le protocole se fonde sur le transfert HTTP de représentations au format Atom. Le format Atom est documenté dans Le format d'agrégation Atom.
xml:base et xml:langapp:categoriesapp:serviceapp:workspaceapp:collectionapp:acceptapp:categoriesPOST
PUTDELETESlug
Slugapp:editedtype
app:control
app:draftapplication/atomcat+xml"application/atomsvc+xml"Slugedit"edit-media"Le protocole de publication Atom est un protocole de niveau supérieur pour la publication et l'édition de ressources web utilisant HTTP [RFC2616] et XML 1.0 [REC-xml]. Le protocole gère la création de ressources web et offre des facilités (facilities) de :
Le protocole de publication Atom diffère de nombreux protocoles actuels en cela qu'une grande latitude est donnée au serveur pour traiter les requêtes des clients. Cf. la section 4.4 pour plus de détails.
Les mots-clés « DOIT », « NE DOIT PAS », « OBLIGATOIRE », « DEVRA », « NE DEVRA PAS », « DEVRAIT », « NE DEVRAIT PAS », « RECOMMANDÉ », « PEUT » et « OPTIONNEL » dans ce document doivent s'interpréter comme décrit dans le document [RFC2119].
Les formats de document du protocole Atom sont définis en fonction de l'ensemble d'information XML (XML Information Set) [REC-xml-infoset], sérialisés comme XML 1.0 [REC-xml].
Les termes Infoset « item d'information d'élément » (element information item) et « item d'information d'attribut » (attribute information item) sont abrégés en « élément » et « attribut » respectivement. Donc, lorsque cette spécification emploie le terme « élément », elle se réfère à un item d'information d'élément, et qu'elle emploie le terme « attribut », à un item d'information d'attribut.
Quelques sections de cette spécification sont illustrées avec des fragments d'un schéma RELAX NG Compact [RNC] non normatif. Par contre, le texte de cette spécification fournit la définition de conformité. Les schémas complets apparaissent en annexe B.
xml:base et xml:langLes éléments XML définis par cette spécification PEUVENT avoir un attribut
xml:base [REC-xmlbase]. Lorsqu'on utilise xml:base, il sert la fonction
décrite à la section 5.1.1 de URI — Syntaxe générique [RFC3986],
en établissant l'adresse URI, ou l'adresse IRI (Internationalized Resource Identifier)
[RFC3987], de base pour résoudre les références relatives trouvées dans la portée de l'attribut xml:base.
Tout élément défini par cette spécification PEUT avoir un attribut xml:lang,
dont le contenu indique le langage naturel de l'élément et ses descendants. Les exigences concernant le contenu et l'interprétation
de xml:lang sont définies à la section 2.12 de XML 1.0 [REC-xml].
Par commodité, on peut se référer à ce protocole comme au « protocole Atom » ou à « AtomPub. Cette spécification utilise la terminologie suivante :
atom:link
avec une relation de "edit" ou "edit-media".
Cf. la section 9.1. Le protocole définit deux types de membre :
rel d'un élément atom:link.Le protocole Atom spécifie des opérations pour publier et éditer des ressources avec HTTP. Il utilise des représentations au format Atom pour décrire l'état et les métadonnées de ces ressources. Il définit comment organiser des collections de ressources et il spécifie des formats pour en permettre la découverte, le regroupement et la catégorisation.
Les documents du protocole Atom autorisent l'utilisation d'adresses IRI [RFC3987] ainsi que d'adresses URI [RFC3986] pour identifier les ressources. Avant que HTTP n'utilise une adresse IRI dans un document, celle-ci est d'abord convertie en une adresse URI conformément à la procédure décrite à la section 3.1 du [RFC3987]. En accord avec cette spécification, la conversion DEVRAIT être appliquée aussi tard que possible. La conversion n'implique pas la création d'une ressource : l'adresse IRI et l'adresse URI en laquelle celle-ci est convertie identifient la même ressource.
Bien que le protocole Atom spécifie les formats des représentations échangées et les actions pouvant être réalisées sur les adresses IRI incorporées dans ces représentations, il ne contraint pas la forme des adresses URI utilisées. HTTP [RFC2616] spécifie que l'espace URI (URI space) de chaque serveur est contrôlé par ce serveur, et ce protocole n'impose pas d'autres contraintes sur ce contrôle.
Une ressource dont l'adresse IRI est listée dans une collection est appelée une ressource membre. Le protocole définit deux types de ressources membres : les ressources d'entrée et les ressources de média. Les ressources d'entrée sont représentées par des documents d'entrée Atom [RFC4287]. Les ressources de média peuvent avoir des représentations dans n'importe quel type de média. Une ressource de média est décrite dans une collection en utilisant une entrée appelée une entrée de lien de média. Ce diagramme montre la classification des ressources dans le protocole Atom :
Ressources membres
|
-----------------
| |
Ressources d'entrée Ressources de média
|
Entrée de lien de média
Le protocole Atom définit des ressources de collection (collection resources) pour gérer et organiser les deux types de ressources membres. Une collection est représentée par un document de fil Atom (Atom feed document). Les entrées d'un fil de collection (collection feed) contiennent les adresses IRI des ressources membres de la collection et les métadonnées les concernant. Un fil de collection peut contenir un nombre quelconque d'entrées, qui peuvent représenter tous les membres de la collection ou un sous-ensemble ordonné de ceux-ci (cf. la section 10.1). Dans le diagramme d'une collection ci-dessous, il y a deux entrées. La première contient l'adresse IRI d'une ressource d'entrée ; la deuxième contient les adresses IRI d'une ressource de média et d'une entrée de lien de média, laquelle contient les métadonnées de cette ressource de média :
Collection
|
o- Entrée
| |
| o- Adresse IRI d'entrée de membre (ressource d'entrée)
|
o- Entrée
|
o- Adresse IRI de membre (entrée de lien de média)
|
o- Adresse IRI de média (ressource de média)
Le protocole Atom ne fait aucune distinction entre les fils (feeds) utilisés pour les collections et les autres fils Atom. Le seul mécanisme fournit par cette spécification pour indiquer qu'un fil est un fil de collection est la présence de l'adresse IRI du fil dans un document de service.
Les documents de service représentent des groupes de collections définies par le serveur et servent à initialiser le processus de création et d'édition des ressources. Ces groupes de collections sont appelés des espaces de travail (workspaces). Les espaces de travail ont des noms mais pas d'adresse IRI et aucun modèle de traitement défini. Le document de service peut indiquer quels types de média et quelles catégories la collection acceptera. Dans le diagramme ci-dessous, il y a deux espaces de travail, chacun décrivant les adresses IRI, les types de média acceptables et les catégories d'une collection :
Service
o- Espace de travail
| |
| o- Collection
| |
| o- Adresse IRI, catégories, types de média
|
o- Espace de travail
|
o- Collection
|
o- Adresse IRI, catégories, types de média
Le protocole de publication Atom utilise les méthodes HTTP pour créer les ressources membres, ainsi :
GET sert à récupérer une représentation d'une ressource connue ;POST sert à créer une nouvelle ressource nommée dynamiquement. Lorsque le client soumet des représentations d'entrées
non-Atom à une collection pour une création, deux ressources sont toujours créées : une entrée de média pour la ressource demandée
et une entrée de lien de média pour les métadonnées à propos de la ressource qui apparaîtra dans la collection ;PUT sert à éditer une ressource connue. Cette méthode ne sert pas pour la création de la ressource ;DELETE sert à supprimer une ressource connue.Le protocole Atom couvre seulement la création, l'édition et la suppression des ressources d'entrée et de média. D'autres ressources pourraient être créées, éditées et supprimées à la suite de la manipulation d'une collection, mais leur nombre, leurs types de média et les effets des opérations du protocole Atom sur celles-ci ne sont pas couverts par cette spécification.
Puisque tous les aspects de l'interaction client-serveur sont définis en fonction de HTTP, on devrait consulter le document [RFC2616] pour tous les champs non couverts par cette spécification.
Le protocole Atom impose peu de restrictions sur les actions des serveurs. À moins d'une contrainte définie ici, on peut s'attendre
à ce que le comportement des serveurs varie, en particulier autour de la manipulation des entrées Atom envoyées par les clients.
Par exemple, bien que cette spécification ne définisse que le comportement attendu des collections par rapport à GET
et POST, cela n'implique pas que les méthodes PUT, DELETE, PROPPATCH et les
autres soient interdites sur les ressources des collections, seulement que cette spécification ne définit pas quelle serait la
réponse du serveur à ces méthodes. De même, bien que quelques codes d'état HTTP soient mentionnés explicitement,
les clients devraient se préparer à manipuler n'importe quel code d'état du serveur. Les serveurs peuvent choisir d'accepter,
rejeter, retarder, modérer, censurer, reformater, traduire, relocaliser ou recatégoriser le contenu qui leur est soumis.
Seuls certains choix sont répercutés immédiatement au client en réponse à ses requêtes ; d'autres choix ne deviendront apparents
que plus tard, dans le fil ou les entrées publiées. La même série de requêtes
auprès de deux sites de publication différents peut produire une série différente de réponses HTTP,
des fils résultants différents ou des contenus d'entrée différents.
Par conséquent, un logiciel client doit être écrit avec flexibilité pour accepter ce que le serveur décidera être les résultats de ses soumissions. Toute réponse du serveur ou toute modification du contenu par le serveur, non interdites explicitement par cette spécification ou par HTTP [RFC2616], sont donc permises.
Bien que des codes d'état HTTP spécifiques soient montrés dans les diagrammes d'interaction ci-dessous,
un client AtomPub devrait être prêt à traiter n'importe quel code d'état. Par exemple, une requête PUT à
l'adresse URI d'un membre pourrait se traduire par le retour d'un code d'état « 204 Pas de contenu » (No Content),
lequel indique quand même un succès.
Client Serveur
| |
| 1.) GET à l'adresse URI du document de service |
|-------------------------------------------------->|
| |
| 2.) 200 Ok |
| Document de service |
|<--------------------------------------------------|
| |
Pour lister les membres d'une collection, le client envoie une requête GET à l'adresse URI d'une
collection. Un document de fil Atom est retourné, dont les entrées contiennent les adresses IRI des ressources membres.
Le fil retourné peut décrire tous les membres d'une collection ou seulement une liste partielle
(cf. la section 10).
Client Serveur
| |
| 1.) GET à l'adresse URI d'une collection |
|-------------------------------------------->|
| |
| 2.) 200 Ok |
| Document de fil Atom |
|<--------------------------------------------|
| |
GET à l'adresse URI de la collection ;
Client Serveur
| |
| 1.) POST à l'adresse URI d'une collection |
| Représentation des membres |
|--------------------------------------------------->|
| |
| 2.) 201 Créé |
| Location: Adresse URI de l'entrée de membre |
|<---------------------------------------------------|
| |
POST d'une représentation du membre à l'adresse URI de la collection ;Location
qui contient l'adresse Une fois créée la ressource et l'adresse URI de membre connue, cette adresse peut être utilisée pour récupérer, éditer et supprimer la ressource. La section 11 décrit des extensions du format d'agrégation Atom utilisées dans le protocole Atom pour des besoins d'édition.
Client Serveur
| |
| 1.) GET à l'adresse URI du membre |
|------------------------------------------>|
| |
| 2.) 200 Ok |
| Représentation du membre |
|<------------------------------------------|
| |
GET à l'adresse URI d'une ressource membre pour en récupérer une représentation ;
Client Serveur
| |
| 1.) PUT à l'adresse URI du membre |
| Représentation du membre |
|------------------------------------------>|
| |
| 2.) 200 OK |
|<------------------------------------------|
PUT pour stocker une représentation d'une ressource membre ;
Client Serveur
| |
| 1.) DELETE à l'adresse URI du membre |
|------------------------------------------>|
| |
| 2.) 200 OK |
|<------------------------------------------|
| |
DELETE à l'adresse URI d'une ressource membre ;Une approche différente est prise pour supprimer les ressources de média ; cf. la section 9.4 pour les détails.
Le protocole Atom utilise les codes d'état de réponse définis dans HTTP pour indiquer le succès ou l'échec d'une opération. Consultez la spécification HTTP [RFC2616] pour les définitions détaillées de chaque code d'état.
On fait remarquer aux implémenteurs (implementers) que, selon la spécification HTTP, les entités de réponse HTTP des types 4xx et 5xx DEVRAIENT inclure une explication intelligible (human-readable) de l'erreur.
Cette spécification définit deux types de documents : les documents de catégorie et les documents de service.
Un document de catégorie (section 7) contient des listes de catégories spécifiées à l'aide de l'élément
atom:category du format d'agrégation Atom (cf. la section 4.2.2 du document [RFC4287]).
Un document de service (section 8) regroupe les collections disponibles en espaces de travail.
Le nom d'espace de noms (namespace) [REC-xml-names] pour l'un ou l'autre type de document est le suivant :
http://www.w3.org/2007/app
Les documents XML du protocole de publication Atom DOIVENT être « bien formés dans un espace de noms » comme indiqué à la section 7 de [REC-xml-names].
Cette spécification utilise le préfixe « app: » comme nom d'espace de noms. Le préfixe « atom: » est utilisé pour "http://www.w3.org/2005/Atom", le nom d'espace de noms du format d'agrégation Atom [RFC4287]. Ces préfixes d'espace de noms n'ont pas d'importance sémantique.
Cette spécification n'établit aucune définition DTD pour les formats du protocole Atom et de ce fait n'exige pas d'eux qu'ils soient « valides » au sens utilisé par [REC-xml].
Le balisage non reconnu dans un document AtomPub est considéré comme étant du « balisage étranger », comme défini à la section 6 du Format d'agrégation Atom [RFC4287]. Sauf indication contraire explicite, on peut employer du balisage étranger n'importe où dans un document de catégorie ou de service. Les processeurs rencontrant du balisage étranger NE DOIVENT PAS interrompre le traitement et NE DOIVENT PAS signaler une erreur. Les clients DEVRAIENT préserver le balisage étranger lors de la transmission de tels documents.
Le nom d'espace de noms "http://www.w3.org/2007/app" est réservé pour une compatibilité ascendante des révisions
des types des documents de catégorie et de service. Cela n'exclut pas l'ajout d'éléments et d'attributs qui ne seraient pas reconnus
par les processeurs conformes à cette spécification. Ce balisage non reconnu issu de l'espace de noms
"http://www.w3.org/2007/app" DOIT être traité comme du balisage étranger.
Les documents de catégorie contiennent des listes de catégories décrites à l'aide de l'élément atom:category
du format d'agrégation Atom [RFC4287]. Les catégories peuvent aussi apparaître dans
les documents de service, où elles indiquent celles permises dans une collection (cf. la section 8.3.6).
Les documents de catégorie sont identifiés par le type de média "application/atomcat+xml"
(cf. la section 16.1).
<?xml version="1.0" ?>
<app:categories
xmlns:app="http://www.w3.org/2007/app"
xmlns:atom="http://www.w3.org/2005/Atom"
fixed="yes" scheme="http://example.com/cats/big3">
<atom:category term="animal" />
<atom:category term="vegetable" />
<atom:category term="mineral" />
</app:categories>
Ce document de catégorie contient des éléments atom:category, avec les termes "animal", "vegetable"
et "mineral". Aucune des catégories n'utilise l'attribut label défini dans le document
[RFC4287]. Elles héritent toutes de l'attribut scheme
"http://example.com/cats/big3" déclaré sur l'élément app:categories. Donc, si la catégorie "mineral"
devait apparaître dans une entrée Atom ou un document de fil Atom, ce serait comme :
<atom:category scheme="http://example.com/cats/big3" term="mineral"/>
app:categoriesLa racine d'un document de catégorie est l'élément app:categories.
Un élément app:categories peut contenir zéro ou plus éléments atom:category
de l'espace de noms du format d'agrégation Atom [RFC4287]
("http://www.w3.org/2005/Atom").
Un sous-élément atom:category sans attribut scheme hérite de celui de son
parent app:categories. Un sous-élément atom:category avec un attribut
scheme n'hérite pas de la valeur de celui de son élément parent app:categories.
atomCategory =
element atom:category {
atomCommonAttributes,
attribute term { text },
attribute scheme { atomURI }?,
attribute label { text }?,
undefinedContent
}
appInlineCategories =
element app:categories {
attribute fixed { "yes" | "no" }?,
attribute scheme { atomURI }?,
(atomCategory*,
undefinedContent)
}
appOutOfLineCategories =
element app:categories {
attribute href { atomURI },
undefinedContent
}
appCategories = appInlineCategories | appOutOfLineCategories
app:categoriesL'élément app:categories peut contenir un attribut fixed, avec une valeur
de "yes" ou bien de "no", indiquant si la liste des catégories est un
ensemble fixe ("yes") ou ouvert. L'absence de l'attribut fixed équivaut à la
présence d'un attribut fixed avec une valeur de "no".
Autrement, l'élément app:categories PEUT contenir un attribut
href dont la valeur DOIT être une référence IRI identifiant
un document de catégorie. Si l'attribut href est fourni, l'élément app:categories
DOIT être vide et NE DOIT PAS avoir d'attributs fixed
ou scheme.
Pour pouvoir commencer la création (authoring), un client a besoin de découvrir les capacités et les emplacements des collections disponibles. Les documents de service sont conçus pour ce processus de découverte.
Les modalités de découverte des documents de service ne sont pas définies dans cette spécification.
Les documents de service sont identifiés par le type de média "application/atomsvc+xml"
(cf. la section 16.2).
Un document de service groupe des collections en espaces de travail (workspaces). Les opérations sur les espaces de travail telles que la création ou la suppression ne sont pas définies par cette spécification. Cette spécification n'attribue aucune signification aux espaces de travail, à savoir qu'un espace de travail n'implique pas de traitements spécifiques.
Il n'y aucune obligation à ce qu'un serveur doive gérer plusieurs espaces de travail. En outre, une collection PEUT apparaître dans plusieurs espaces de travail.
<?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://www.w3.org/2007/app"
xmlns:atom="http://www.w3.org/2005/Atom">
<workspace>
<atom:title>Main Site</atom:title>
<collection
href="http://example.org/blog/main" >
<atom:title>My Blog Entries</atom:title>
<categories
href="http://example.com/cats/forMain.cats" />
</collection>
<collection
href="http://example.org/blog/pic" >
<atom:title>Pictures</atom:title>
<accept>image/png</accept>
<accept>image/jpeg</accept>
<accept>image/gif</accept>
</collection>
</workspace>
<workspace>
<atom:title>Sidebar Blog</atom:title>
<collection
href="http://example.org/sidebar/list" >
<atom:title>Remaindered Links</atom:title>
<accept>application/atom+xml;type=entry</accept>
<categories fixed="yes">
<atom:category
scheme="http://example.org/extra-cats/"
term="joke" />
<atom:category
scheme="http://example.org/extra-cats/"
term="serious" />
</categories>
</collection>
</workspace>
</service>
Le document de service ci-dessus décrit deux espaces de travail. Le premier appelé « Main Site » a deux collections
intitulées « My Blog Entries » et « Pictures », dont les adresses IRI sont "http://example.org/blog/main"
et "http://example.org/blog/pic" respectivement. La collection « Pictures » inclut trois éléments accept
indiquant les types des fichiers d'image que le client peut envoyer à la collection pour créer de nouvelles ressources de média
(les entrées associées aux ressources de média sont expliquées à la section 9.6).
Le deuxième espace de travail appelé « Sidebar Blog » a une seule collection intitulée « Remaindered Links » dont
l'adresse IRI est "http://example.org/sidebar/list". La collection a un élément accept
dont le contenu est "application/atom+xml;type=entry", indiquant qu'elle acceptera les entrées Atom d'un client.
Dans chacune des deux collections d'entrées, l'élément categories fournit une liste des
catégories disponibles pour les entrées de membre. Dans la collection « My Blog Entries », la liste des catégories disponibles
est mise à disposition au travers de l'attribut href. La collection « Sidebar Blog » fournit une
liste de catégories dans le document de service mais déclare celle-ci fixe, en signalant une requête du serveur selon laquelle
les entrées doivent être envoyées par la méthode POST en employant uniquement ces deux catégories.
app:serviceLa racine d'un document de service est l'élément app:service.
L'élément app:service est le conteneur des informations de service associées à un ou plusieurs
espaces de travail. Un élément app:service DOIT contenir un ou plusieurs
éléments app:workspace.
namespace app = "http://www.w3.org/2007/app"
start = appService
appService =
element app:service {
appCommonAttributes,
( appWorkspace+
& extensionElement* )
}
app:workspaceLes espaces de travail sont des groupes de collections définis par le serveur. L'élément app:workspace
contient zéro ou plus éléments app:collection décrivant les collections de ressources disponibles pour
l'édition.
appWorkspace =
element app:workspace {
appCommonAttributes,
( atomTitle
& appCollection*
& extensionSansTitleElement* )
}
atomTitle = element atom:title { atomTextConstruct }
atom:titleL'élément app:workspace DOIT contenir un élément atom:title
(comme défini dans le document [RFC4287]), lequel donne un titre intelligible à l'espace de travail.
app:collectionL'élément app:collection décrit une collection. L'élément app:collection
DOIT contenir un élément atom:title.
L'élément app:collection PEUT contenir un nombre quelconque
d'éléments app:accept, lesquels indiquent les types des représentations acceptées par la collection.
L'ordre de ces éléments n'est pas significatif.
L'élément app:collection PEUT contenir un nombre quelconque
d'éléments app:categories.
appCollection =
element app:collection {
appCommonAttributes,
attribute href { atomURI },
( atomTitle
& appAccept*
& appCategories*
& extensionSansTitleElement* )
}
hrefL'élément app:collection DOIT contenir un attribut href,
dont la valeur donne l'adresse IRI de la collection.
atom:titleL'élément atom:title est défini dans le document [RFC4287] ;
il donne un titre intelligible à la collection.
app:acceptLa valeur d'un élément app:accept est une gamme de médias (media range),
comme défini dans le document [RFC2616]. La gamme de médias spécifie un type de représentation
que l'on peut envoyer par la méthode POST à une collection.
L'élément app:accept est similaire à l'en-tête de requête HTTP Accept
[RFC2616]. Les paramètres de type de média sont admis dans l'élément app:accept
mais app:accept n'a aucune notion de préférence : les arguments accept-params ou q,
définis à la section 14.1 de [RFC2616], ne sont pas significatifs.
Les caractères blancs (white space), comme défini dans [REC-xml],
autour de la gamme de médias de l'élément app:accept ne sont pas significatifs
et DOIVENT être ignorés.
Une valeur de "application/atom+xml;type=entry" PEUT apparaître dans une
liste app:accept de gammes de médias ; elle indique que l'on peut envoyer par la méthode POST
des documents d'entrée Atom à la collection. Si aucun élément app:accept n'est présent,
les clients DEVRAIENT traiter cela comme équivalent à un élément app:accept
avec le contenu "application/atom+xml;type=entry".
S'il existe un seul élément app:accept et qu'il est vide, les clients DEVRAIENT
en déduire que la collection ne permet pas la création de nouvelles entrées.
appAccept =
element app:accept {
appCommonAttributes,
( text? )
}
L'élément app:collection PEUT apparaître comme sous-élément
d'un élément atom:feed ou atom:source dans un document de fil Atom.
Son contenu identifie une collection par laquelle on peut ajouter de nouvelles entrées pour les faire apparaître dans le fil.
Lorsqu'il apparaît dans un élément atom:feed ou atom:source,
l'élément app:collection est considéré comme étant du balisage étranger, tel que défini à la section 6
du document [RFC4287].
app:categoriesL'élément app:categories fournit une liste de catégories applicables aux membres d'une collection.
Cf. la section 7.2.1 pour une définition détaillée de l'élément app:categories.
Le serveur PEUT rejeter les tentatives de créer ou stocker des membres dont les catégories
ne sont pas présentes dans sa liste de catégories. Une collection qui indique un ensemble ouvert de catégories
NE DEVRAIT PAS rejeter des membres par ailleurs acceptables dont les catégories ne sont pas dans sa
liste de catégories. L'absence d'un élément app:categories signifie que la gestion des catégories de
la collection n'est pas définie. Une liste de catégories fixe (fixed="yes") contenant zéro catégorie
indique que la collection n'accepte pas de données catégoriques.
L'adresse URI d'un membre permet aux clients de récupérer, éditer et supprimer une ressource membre en utilisant
les méthodes HTTP GET, PUT et DELETE. Les ressources d'entrée sont représentées
par des documents d'entrée Atom.
Les adresses URI des membres apparaissent à deux endroits. Elles sont retournées dans une en-tête Location
après la création réussie d'une ressource avec la méthode POST, comme décrit dans la section 9.2
ci-dessous. Elles peuvent aussi apparaître dans les entrées d'un fil de collection, en tant qu'éléments atom:link
avec une relation de lien de "edit".
Une entrée de membre DEVRAIT contenir un tel élément atom:link avec une
relation de lien de "edit", qui indique l'adresse URI du membre.
POSTPour ajouter des membres à une collection, les clients envoient des requêtes POST à l'adresse URI de
la collection.
Une création de membre réussie est indiquée par un code de réponse de « 201 Créé » (Created). Lorsque la collection répond par un code d'état
de 201, elle DEVRAIT également retourner un corps de réponse qui DOIT être
un document d'entrée Atom représentant la ressource nouvellement créée. Puisque le serveur est libre d'altérer l'entrée créée par
la méthode POST, par exemple en changeant le contenu de l'élément atom:id, le retour de
l'entrée peut être utile au client, en lui permettant de corréler les vues du client et du serveur pour la nouvelle entrée.
Lorsqu'une ressource membre est créée, son adresse URI de membre DOIT être
retournée dans une en-tête Location avec la réponse de la collection.
Si la requête de création contenait un document d'entrée Atom et que la réponse à suivre du serveur contient une en-tête
Content-Location qui correspond caractère-pour-caractère à l'en-tête Location, alors le client est autorisé
à interpréter l'entité de réponse comme étant la représentation complète de l'entrée nouvellement créée. Sans en-tête
Content-Location correspondante, le client NE DOIT PAS supposer que l'entité retournée
est une représentation complète de la ressource créée.
Le corps de requête envoyé avec la requête POST n'a pas besoin d'être une entrée Atom. Par exemple,
ce pourrait être une image ou un film. Les collections PEUVENT retourner une réponse avec un
code d'état de « 415 Type de média non géré » (Unsupported media type) pour indiquer que le type de média de l'entité envoyée par la méthode POST
n'est pas permis ou géré par la collection. Pour une explication des problèmes rencontrés lors de la création d'un tel contenu,
cf. la section 9.6.
Ci-dessous, le client envoie une requête POST contenant une représentation d'entrée Atom utilisant
l'adresse URI de la collection :
POST /edit/ HTTP/1.1
Host: example.org
User-Agent: Thingio/1.0
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Type: application/atom+xml;type=entry
Content-Length: nnn
Slug: First Post
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Atom-Powered Robots Run Amok</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2003-12-13T18:30:02Z</updated>
<author><name>John Doe</name></author>
<content>Some text.</content>
</entry>
Le serveur signale une création réussie par un code d'état de 201. La réponse inclut une en-tête Location indiquant
l'adresse URI d'entrée du membre de l'entrée Atom et une représentation de cette entrée dans le corps de la réponse.
HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml;type=entry;charset="utf-8"
Location: http://example.org/edit/first-post.atom
ETag: "c180de84f991g8"
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Atom-Powered Robots Run Amok</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2003-12-13T18:30:02Z</updated>
<author><name>John Doe</name></author>
<content>Some text.</content>
<link rel="edit"
href="http://example.org/edit/first-post.atom"/>
</entry>
L'entrée créée et retournée par la collection ne correspondra peut-être pas à l'entrée envoyée avec POST par
le client. Un serveur PEUT changer les valeurs des divers éléments dans l'entrée, telles que
atom:id, atom:updated et atom:author,
et PEUT choisir de supprimer ou d'ajouter d'autres éléments et attributs, ou changer le contenu des
éléments et les valeurs des attributs.
PUTPour éditer une ressource membre, un client envoie une requête PUT à son adresse URI de membre,
comme spécifié dans le document [RFC2616].
Pour éviter une perte accidentelle de données lors de l'édition d'entrées de membre ou d'entrées de lien de média, un client utilisant le protocole Atom DEVRAIT conserver toutes les métadonnées qui n'ont pas été modifiées volontairement, y compris le balisage étranger inconnu, comme défini à la section 6 du document [RFC4287].
DELETEPour supprimer une ressource membre, un client envoie une requête DELETE à son adresse URI de membre,
comme spécifié dans le document [RFC2616]. La suppression d'une entrée de lien de média
DEVRAIT aboutir à la suppression de la ressource de média correspondante.
On invite les implémenteurs à prêter attention aux contrôles de cache et à utiliser les mécanismes disponibles dans HTTP
lors de l'édition des ressources, en particulier les étiquettes d'entité (entity-tags) comme
souligné dans le document [NOTE-detect-lost-update]. Les clients n'ont pas
l'assurance de recevoir les représentations les plus récentes des membres de collection avec la méthode GET si le
serveur autorise des intermédiaires à les mettre en cache.
Ci-dessous, le client crée une entrée de membre avec la méthode POST:
POST /myblog/entries HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Type: application/atom+xml;type=entry
Content-Length: nnn
Slug: First Post
<?xml version="1.0" ?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Atom-Powered Robots Run Amok</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2007-02-123T17:09:02Z</updated>
<author><name>Captain Lansing</name></author>
<content>It's something moving... solid metal</content>
</entry>
Le serveur signale une création réussie par un code d'état de 201 et retourne une en-tête ETag dans la réponse.
Puisqu'ici le serveur a retourné une en-tête Content-Location et une en-tête Location avec la même valeur,
la représentation d'entrée retournée peut être comprise comme étant une représentation complète de l'entrée nouvellement créée
(cf. la section 9.2).
HTTP/1.1 201 Created
Date: Fri, 23 Feb 2007 21:17:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml;type=entry
Location: http://example.org/edit/first-post.atom
Content-Location: http://example.org/edit/first-post.atom
ETag: "e180ee84f0671b1"
<?xml version="1.0" ?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Atom-Powered Robots Run Amok</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2007-02-123T17:09:02Z</updated>
<author><name>Captain Lansing</name></author>
<content>It's something moving... solid metal</content>
</entry>
Le client peut à sa convenance utiliser la valeur ETag retournée pour construire ensuite une
« requête GET conditionnelle », comme défini dans le document [RFC2616]. Auquel cas,
préalablement à l'édition, le client envoie la valeur ETag du membre en utilisant l'en-tête If-None-Match.
GET /edit/first-post.atom HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
If-None-Match: "e180ee84f0671b1"
Si l'entrée n'a pas été modifiée, la réponse sera un code d'état de « 304 Non modifié » (Not Modified). Cela permet au client de déterminer s'il a toujours la représentation la plus récente de l'entrée au moment de l'édition.
HTTP/1.1 304 Not Modified
Date: Sat, 24 Feb 2007 13:17:11 GMT
Après l'édition, le client peut effectuer une requête PUT de l'entrée et envoyer la valeur d'entité ETag
dans une en-tête If-Match, informant le serveur d'accepter l'entrée à condition que la valeur d'entité envoyée
corresponde à celle du serveur.
PUT /edit/first-post.atom HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Type: application/atom+xml;type=entry
Content-Length: nnn
If-Match: "e180ee84f0671b1"
<?xml version="1.0" ?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Atom-Powered Robots Run Amok</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2007-02-24T16:34:06Z</updated>
<author><name>Captain Lansing</name></author>
<content>Update: it's a hoax!</content>
</entry>
Mais entre temps le serveur a reçu une copie plus récente que celle du client et il répond par un code d'état de « 412 Échec de la condition préalable » (Precondition Failed).
HTTP/1.1 412 Precondition Failed
Date: Sat, 24 Feb 2007 16:34:11 GMT
Cela informe le client de ce que le serveur a une version plus récente de l'entrée et qu'il ne permettra pas le stockage de l'entité envoyée.
Un client peut envoyer à une collection via la méthode POST des ressources de média ainsi que des ressources d'entrée.
Si un serveur accepte une telle requête, alors il DOIT créer deux nouvelles ressources : l'une qui
correspond à l'entité envoyée dans la requête, appelée ressource de média, l'autre qui correspond à une entrée de membre associée,
appelée entrée de lien de média (media link entry). Les entrées de lien de média
sont représentées par des entrées Atom et apparaissent dans la collection.
L'entrée de lien de média contient les métadonnées et l'adresse IRI de la ressource de média (peut-être non textuelle). L'entrée de lien de média met donc à disposition séparément les métadonnées à propos de la ressource de média pour la récupération et la modification.
Le serveur peut signaler les types de média qu'il acceptera à l'aide de l'élément atom:accept dans
le document de service, comme défini à la section 8.3.4.
Les réponses positives aux requêtes en création DOIVENT inclure l'adresse URI de
l'entrée de lien de média dans l'en-tête Location. L'entrée de lien de média DEVRAIT
contenir un élément atom:link avec une relation de lien de "edit-media"
indiquant l'adresse URI de la ressource de média. L'entrée de lien de média DOIT avoir
un élément atom:content avec un attribut src. La valeur de src
est l'adresse IRI de la ressource de média nouvellement créée. Il est OPTIONNEL que
l'adresse IRI de l'attribut src sur l'élément atom:content
soit la même que celle de la ressource de média. Par exemple, l'attribut src pourrait à la place être
un lien dans un cache statique ou un réseau de distribution de contenu (content distribution network)
et non l'adresse IRI de la ressource de média.
Les implémenteurs sont priés de noter que le document [RFC4287] spécifie que les entrées Atom
DOIVENT contenir un élément atom:summary. De fait, à la création réussie d'une
entrée de lien de média, un serveur PEUT choisir de peupler l'élément atom:summary
(ainsi que tous les autres éléments obligatoires tels que atom:id, atom:author
et atom:title) avec un contenu dérivé de l'entité postée (POST) ou de toute autre source.
Le serveur pourrait interdire à un client de modifier les valeurs qu'il a sélectionnées pour ces éléments.
Pour la création d'une ressource, cette spécification ne définit que les cas où le corps de la requête POST a une
entité d'entrée Atom déclarée comme un type de média Atom ("application/atom+xml"), ou une entité non-Atom
déclarée comme un type de média non-Atom. Lorsqu'un client poste (POST) une entrée Atom à une collection, il peut
utiliser un type de média de "application/atom+xml" ou bien de "application/atom+xml;type=entry".
Cette spécification ne spécifie aucune sémantique de requête ou comportement de serveur au cas où le type de la requête POST
est "application/atom+xml" et que le corps est autre chose qu'une entrée Atom. En particulier,
ce qu'il advient au postage (POST) d'un document de fil Atom à une collection avec le type de média
"application/atom+xml" n'est pas défini.
Le protocole Atom ne spécifie aucun moyen de créer plusieurs représentations de la même ressource (par exemple, une version PNG et JPG de la même image), que ce soit à la création ou à l'édition.
Ci-dessous, le client envoie une requête POST contenant une image PNG à l'adresse URI
d'une collection acceptant les images PNG :
POST /edit/ HTTP/1.1
Host: media.example.org
Content-Type: image/png
Slug: The Beach
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: nnn
...données binaires...
Le serveur signale une création réussie par un code d'état de 201. La réponse inclut une en-tête Location
indiquant l'adresse URI de membre de l'entrée de lien de média et une représentation de cette entrée dans le corps
de la réponse. L'entrée de lien de média inclut un élément de contenu avec un attribut src. Elle contient
également un lien avec une relation de lien de "edit-media", indiquant l'adresse IRI à
utiliser pour modifier la ressource de média.
HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml;type=entry;charset="utf-8"
Location: http://example.org/media/edit/the_beach.atom
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>The Beach</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2005-10-07T17:17:08Z</updated>
<author><name>Daffy</name></author>
<summary type="text" />
<content type="image/png"
src="http://media.example.org/the_beach.png"/>
<link rel="edit-media"
href="http://media.example.org/edit/the_beach.png" />
<link rel="edit"
href="http://example.org/media/edit/the_beach.atom" />
</entry>
Plus tard, le client envoie une requête PUT contenant la nouvelle image PNG en utilisant
l'adresse URI indiquée dans le lien "edit-media" de l'entrée de lien de média :
PUT /edit/the_beach.png HTTP/1.1
Host: media.example.org
Content-Type: image/png
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: nnn
...données binaires...
Le serveur signale une édition réussie par un code d'état de 200 :
HTTP/1.1 200 Ok
Date: Fri, 8 Oct 2006 17:17:11 GMT
Le client peut éditer les métadonnées de l'image. D'abord obtenir (GET) l'entrée de lien de média :
GET /media/edit/the_beach.atom HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
L'entrée de lien de média est retournée :
HTTP/1.1 200 Ok
Date: Fri, 7 Oct 2005 17:18:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml;type=entry;charset="utf-8"
ETag: "c181bb840673b5"
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>The Beach</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2005-10-07T17:17:08Z</updated>
<author><name>Daffy</name></author>
<summary type="text" />
<content type="image/png"
src="http://media.example.org/the_beach.png"/>
<link rel="edit-media"
href="http://media.example.org/edit/the_beach.png" />
<link rel="edit"
href="http://example.org/media/edit/the_beach.atom" />
</entry>
Les métadonnées peuvent être mises à jour, ici pour ajouter un résumé en retour au serveur (PUT) :
PUT /media/edit/the_beach.atom HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Type: application/atom+xml;type=entry
Content-Length: nnn
If-Match: "c181bb840673b5"
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>The Beach</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2005-10-07T17:17:08Z</updated>
<author><name>Daffy</name></author>
<summary type="text">
A nice sunset picture over the water.
</summary>
<content type="image/png"
src="http://media.example.org/the_beach.png"/>
<link rel="edit-media"
href="http://media.example.org/edit/the_beach.png" />
<link rel="edit"
href="http://example.org/media/edit/the_beach.atom" />
</entry>
La mise à jour a réussi :
HTTP/1.1 200 Ok
Date: Fri, 7 Oct 2005 17:19:11 GMT
Content-Length: 0
On peut ajouter plusieurs ressources de média à la collection :
POST /edit/ HTTP/1.1
Host: media.example.org
Content-Type: image/png
Slug: The Pier
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: nnn
...données binaires...
La ressource a bien été créée :
HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml;type=entry;charset="utf-8"
Location: http://example.org/media/edit/the_pier.atom
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>The Pier</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efe6b</id>
<updated>2005-10-07T17:26:43Z</updated>
<author><name>Daffy</name></author>
<summary type="text" />
<content type="image/png"
src="http://media.example.org/the_pier.png"/>
<link rel="edit-media"
href="http://media.example.org/edit/the_pier.png" />
<link rel="edit"
href="http://example.org/media/edit/the_pier.atom" />
</entry>
Le client peut maintenant créer une nouvelle entrée Atom dans la collection d'entrées de blogue qui référence les deux ressources de média nouvellement créées :
POST /blog/ HTTP/1.1
Host: example.org
Content-Type: application/atom+xml;type=entry
Slug: A day at the beach
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: nnn
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>A fun day at the beach</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6b</id>
<updated>2005-10-07T17:40:02Z</updated>
<author><name>Daffy</name></author>
<content type="xhtml">
<xhtml:div xmlns:xhtml="http://www.w3.org/1999/xhtml">
<xhtml:p>We had a good day at the beach.
<xhtml:img alt="the beach"
src="http://media.example.org/the_beach.png"/>
</xhtml:p>
<xhtml:p>Later we walked down to the pier.
<xhtml:img alt="the pier"
src="http://media.example.org/the_pier.png"/>
</xhtml:p>
</xhtml:div>
</content>
</entry>
La ressource a bien été créée :
HTTP/1.1 200 Ok
Date: Fri, 7 Oct 2005 17:20:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml;type=entry;charset="utf-8"
Location: http://example.org/blog/atom/a-day-at-the-beach.atom
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>A fun day at the beach</title>
<id>http://example.org/blog/a-day-at-the-beach.xhtml</id>
<updated>2005-10-07T17:43:07Z</updated>
<author><name>Daffy</name></author>
<content type="xhtml">
<xhtml:div xmlns:xhtml="http://www.w3.org/1999/xhtml">
<xhtml:p>We had a good day at the beach.
<xhtml:img alt="the beach"
src="http://media.example.org/the_beach.png"/>
</xhtml:p>
<xhtml:p>Later we walked down to the pier.
<xhtml:img alt="the pier"
src="http://media.example.org/the_pier.png"/>
</xhtml:p>
</xhtml:div>
</content>
<link rel="edit"
href="http://example.org/blog/edit/a-day-at-the-beach.atom"/>
<link rel="alternate" type="text/html"
href="http://example.org/blog/a-day-at-the-beach.html"/>
</entry>
Notez que l'entrée retournée contient un lien avec une relation de "alternate" qui pointe vers la
page HTML associée qui a été créée — cette spécification ne l'impose pas mais elle est incluse pour montrer les types
de changement qu'un serveur peut effectuer sur une entrée.
SlugSlug est une en-tête d'entité HTTP (HTTP entity-header)
dont la présence dans une requête POST à une collection constitue une demande du client pour utiliser la valeur
de l'en-tête comme partie des adresses URI qui serait utilisées pour récupérer les ressources d'entrée ou de média
à créer.
Les serveurs PEUVENT utiliser la valeur de l'en-tête Slug lors de la création de
l'adresse URI de membre de la ressource nouvellement créée, par exemple en utilisant une partie ou tous les mots dans
la valeur du dernier segment d'adresse URI. Les serveurs PEUVENT aussi utiliser la valeur
pour la création de l'identificateur atom:id, ou comme titre d'une entrée de lien de média
(cf. la section 9.6).
Les serveurs PEUVENT choisir d'ignorer l'en-tête d'entité Slug. Les serveurs
PEUVENT modifier la valeur de l'en-tête avant de l'utiliser. Par exemple, un serveur pourrait écarter
(filter out) certains caractères ou remplacer les lettres accentuées par de non accentuées,
remplacer les espaces par des caractères TIRET BAS (U+005F), changer la casse, et ainsi de suite.
SlugLa syntaxe de l'en-tête Slug est définie à l'aide la syntaxe BNF augmentée, définie à la
section 2.1 du document [RFC2616] :
LWS = <défini à la section 2.2 de [RFC2616]>
slugtext = %x20-7E | LWS
Slug = "Slug" ":" *slugtext
La valeur du champs est la valeur codée en pourcentage (percent-encoded) du codage UTF-8 de la séquence de caractères à inclure (cf. la section 2.1 de [RFC3986] pour la définition du codage en pourcentage et [RFC3629] pour la définition du codage UTF-8).
Note de mise en œuvre :
Pour produire la valeur de champs depuis une séquence de caractères, d'abord la coder en utilisant le codage UTF-8, puis coder
tous les octets hors des intervalles %20-24 et %26-7E avec un codage en pourcentage (%25 est le code ASCII de « % »,
et a donc besoin d'avoir un codage d'échappement (escaped)). Pour consommer la valeur de champs,
d'abord inverser le codage en pourcentage, puis passer la séquence d'octets résultante au travers d'un processus de décodage UTF-8.
Voici un exemple d'en-tête Slug qui utilise un codage en pourcentage pour représenter le caractère Unicode U+00E8
(LETTRE MINUSCULE LATINE E ACCENT GRAVE) :
POST /myblog/entries HTTP/1.1
Host: example.org
Content-Type: image/png
Slug: The Beach at S%C3%A8te
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: nnn
...données binaires...
Cf. la section 9.2.1 pour un exemple d'en-tête Slug appliquée à la création d'une
ressource d'entrée.
Les ressources de collection DOIVENT fournir des représentations sous la forme de documents de fil Atom dont les entrées contiennent les adresses IRI des membres de la collection. On ne fait aucune distinction entre les fils de collection et les autres types de fil — un fil peut agir à la fois comme fil « public » pour les besoins de l'abonnement et comme fil de collection.
Chaque entrée dans le document de fil DEVRAIT avoir un élément atom:link
avec une relation de "edit" (cf. la section 11.1).
Les entrées dans le fil Atom retourné DEVRAIENT être ordonnées selon leur propriété app:edited,
les dernières entrées éditées apparaissant en premier dans l'ordre du document. La valeur app:edited
n'est pas équivalente à celle de l'en-tête HTTP Last-Modified et ne peut pas être utilisée pour déterminer
la fraîcheur des réponses mises en cache.
Les clients NE DOIVENT PAS supposer qu'une entrée Atom retournée dans le fil est une représentation complète
d'une ressource d'entrée et DEVRAIENT effectuer une requête GET à l'adresse URI
de l'entrée du membre avant de l'éditer. Cf. la section 9.5 pour une discussion sur les implications
des directives de contrôle de cache lors de l'obtention des entrées.
Les collections peuvent contenir un grand nombre de ressources. Un client, tel un robot indexeur (web spider)
ou un navigateur web, pourrait être submergé par le résultat d'une requête GET qui contiendrait toutes les entrées
d'une collection — et de son côté le serveur gâcherait aussi de la bande passante et du temps de calcul à générer une réponse
qui ne peut pas être traitée. Pour cette raison, les serveurs PEUVENT répondre aux requêtes GET
par un document de fil contenant une liste partielle des membres de la collection et un lien vers la liste partielle suivante,
le cas échéant. La première liste partielle retournée DOIT avoir un élément atom:link
avec une relation "next" dont la valeur href est l'adresse URI de
la liste partielle suivante de la collection. Cette liste partielle suivante contiendra l'ensemble des ressources membres éditées
le plus récemment (et un élément atom:link pour la liste partielle à suivre, le cas échéant).
Outre la relation "next", les fils de liste partielle PEUVENT contenir
des éléments de lien dont les attributs rel ont la valeur "previous",
"first" ou "last", lesquels sont utilisables pour naviguer dans l'ensemble complet
des entrées dans la collection.
Par exemple, supposons qu'un client reçoive l'adresse URI "http://example.org/entries/go" d'une collection
d'entrées de membre pour laquelle la politique du serveur est de ne pas générer de documents de fil contenant plus de dix entrées.
Le document de fil de la collection représentera alors la première liste partielle d'un ensemble de dix documents de fil liés.
La relation "first" référence le premier document de fil dans l'ensemble et la relation "last"
le dernier document de fil dans l'ensemble. Dans chaque document, les relations de lien "previous" et
"next" référencent les documents précédent et suivant.
<feed xmlns="http://www.w3.org/2005/Atom">
<link rel="first"
href="http://example.org/entries/go" />
<link rel="next"
href="http://example.org/entries/2" />
<link rel="last"
href="http://example.org/entries/10" />
...
</feed>
Les éléments de lien "previous" et "next" du fil de liste partielle situé à
"http://example.org/entries/2" ressemblerait à ceci :
<feed xmlns="http://www.w3.org/2005/Atom">
<link rel="first"
href="http://example.org/entries/go" />
<link rel="previous"
href="http://example.org/entries/go" />
<link rel="next"
href="http://example.org/entries/3" />
<link rel="last"
href="http://example.org/entries/10" />
...
</feed>
app:editedL'élément app:edited est une structure de date (telle que définie par le document
[RFC4287]), dont le contenu indique la dernière fois où une entrée a été éditée. Si l'entrée n'a pas
encore été éditée, le contenu indique sa date de création. Les éléments d'entrée Atom dans les documents de collection
DEVRAIENT contenir un élément app:edited et NE DOIVENT PAS
en contenir plus d'un.
appEdited = element app:edited ( atomDateConstruct )
Le serveur DEVRAIT changer la valeur de cet élément à chaque fois qu'une ressource d'entrée ou une ressource de média associée sont édités.
edit"Cette spécification ajoute la valeur "edit" au registre des relations de lien Atom
(cf. la section 7.1 de [RFC4287]). La valeur "edit" spécifie que la valeur
de l'attribut href est l'adresse IRI d'une entrée de membre éditable. Lorsqu'elle apparaît
dans un élément atom:entry, l'adresse IRI de href peut être utilisée
pour récupérer, mettre à jour et supprimer la ressource représentée par cette entrée. Un élément atom:entry
NE DOIt PAS contenir plus d'une relation de lien "edit".
edit-media"Cette spécification ajoute la valeur "edit-media" au registre des relations de lien Atom
(cf. la section 7.1 de [RFC4287]). Lorsqu'elle apparaît dans un élément atom:entry,
la valeur de l'attribut href peut être utilisée pour modifier une ressource de média associée à cette entrée.
Un élément atom:entry PEUT contenir zéro ou plus relations de lien
"edit-media". Un élément atom:entry NE DOIT PAS
contenir plus d'un élément atom:link ayant une valeur d'attribut rel de
"edit-media" avec les mêmes valeurs d'attribut type et
hreflang. Toutes les relations de lien "edit-media" dans la même entrée
référencent la même ressource. Si un client rencontre plusieurs relations de lien "edit-media"
dans une entrée, il DEVRAIT alors choisir un lien en fonction de ses préférences pour
type et hreflang. Si un client rencontre plusieurs relations de lien
"edit-media" dans une entrée et n'a aucune préférence concernant les attributs type
et hreflang, alors il DEVRAIT sélectionner la première relation de lien
"edit-media" dans l'ordre du document.
Le format d'agrégation Atom [RFC4287] définit le type de média "application/atom+xml"
pour identifier les documents de fil Atom aussi bien que les documents d'entrée Atom. L'expérience de mise en œuvre a montré
que les documents de fil et d'entrée Atom peuvent avoir des modèles de traitement différents et qu'il y a des situations où il faut
les différencier. Cette spécification définit un paramètre type pour différencier les deux types de
documents Atom.
typeCette spécification définit un nouveau paramètre type à utiliser avec le type de média
"application/atom+xml". Le paramètre type a une valeur de "entry"
ou de "feed".
Ni le nom du paramètre ni sa valeur ne dépendent de la casse.
La valeur "entry" indique que le type de média identifie un document d'entrée Atom. L'élément racine
du document DOIT être atom:entry.
La valeur "feed" indique que le type de média identifie un document de fil Atom. L'élément racine
du document DOIT être atom:feed.
S'il n'est pas indiqué, le type est réputé non défini, obligeant les processeurs Atom à examiner l'élément racine pour déterminer le type de document Atom.
Les nouvelles spécifications PEUVENT imposer l'utilisation du paramètre type
pour identifier le type de document Atom. Les créateurs de documents d'entrée Atom DEVRAIENT utiliser
le paramètre type indépendamment du fait qu'il soit obligatoire ou non. Les créateurs de documents de fil Atom
PEUVENT utiliser le paramètre.
Les processeurs Atom qui ne reconnaissent pas le paramètre type DOIVENT
ignorer sa valeur et examiner l'élément racine pour déterminer le type du document.
Les processeurs Atom qui reconnaissent le paramètre type DEVRAIENT
détecter et signaler les incohérences entre la valeur du paramètre et le type réel de l'élément racine du document.
Cette spécification définit une extension structurée au format Atom, comme défini à la section 6 du document
[RFC4287], pour le contrôle de la publication au sein de l'espace de noms
"http://www.w3.org/2007/app".
app:control
namespace app = "http://www.w3.org/2007/app"
pubControl =
element app:control {
atomCommonAttributes,
pubDraft?
& extensionElement
}
pubDraft =
element app:draft { "yes" | "no" }
L'élément app:control PEUT apparaître comme sous-élément d'une entrée
atom:entry en cours de création ou de mise à jour via le protocole de publication Atom.
L'élément app:control DOIT apparaître juste une seule fois dans une entrée.
L'élément app:control est considéré comme étant du balisage étranger, tel que défini à la section 6
du document [RFC4287].
L'élément app:control et ses sous-éléments PEUVENT être inclus dans les
documents de fil ou d'entrée Atom.
L'élément app:control peut contenir un élément app:draft, comme défini ci-dessous,
et il peut contenir des éléments d'extension, comme défini à la section 6 du document [RFC4287].
app:draftL'inclusion de l'élément app:draft constitue une requête du client afin de contrôler la visibilité
d'une ressource membre. L'élément app:draft PEUT être ignoré par le serveur.
Le nombre d'éléments app:draft dans app:control DOIT
être de zéro ou de un. Le contenu d'un élément app:draft DOIT être
"yes" ou "no". Si l'élément contient la valeur "no",
cela indique une requête du client afin que la ressource membre puisse être visible du public. Si l'élément app:draft
est absent, alors les serveurs compatibles avec l'extension DOIVENT agir comme si
un élément app:draft contenant la valeur "no" avait été envoyé.
Le protocole de publication Atom se fonde sur HTTP. Les exigences d'authentification pour HTTP sont couvertes à la section 11 du document [RFC2616].
L'utilisation de mécanismes d'authentification pour empêcher l'envoi (POST) ou l'édition par des clients inconnus
ou non accrédités est RECOMMANDÉE mais non obligatoire. Si aucune authentification n'est utilisée,
les clients et les serveurs sont vulnérables à des attaques banales par usurpation d'identité (spoofing),
par saturation (denial-of-service) et par vandalisme (defacement).
Toutefois ce risque est acceptable est dans certains contextes.
Le type d'authentification déployé est une décision locale prise par l'exploitant du serveur. Les clients rencontreront probablement des schémas d'authentification qui varieront entre les déploiements de serveurs. Au minimum, les mises en œuvre de clients et de serveurs DOIVENT pouvoir être configurées pour utiliser l'authentification de base HTTP (HTTP Basic Authentication) [RFC2617] conjointement à une connexion effectuée avec TLS 1.0 [RFC2246] ou une version ultérieure normalisée de TLS (telle que [RFC4346]), en gérant les conventions d'utilisation de HTTP sur TLS décrites dans le document [RFC2818].
Le choix du mécanisme d'authentification aura un impact sur l'interopérabilité. Le niveau de sécurité minimum indiqué ci-dessus (authentification de base avec TLS) est vu comme une bonne pratique pour les applications Internet au moment de la publication de cette spécification et suffit pour établir une ligne de base pour l'interopérabilité. Les implémenteurs sont invités à explorer et utiliser d'autres mécanismes jugés aussi bons ou meilleurs au moment du déploiement. Il est RECOMMANDÉ de concevoir les clients de façon à pouvoir déployer de nouveaux schémas d'authentification.
Puisque ce protocole utilise les codes d'état des réponses HTTP comme moyen principal de signaler le résultat d'une requête, la recommandation est que les serveurs répondent aux requêtes non autorisées ou non authentifiées par un code de réponse HTTP de type 4xx approprié (par exemple, « 401 Non autorisé » (Unauthorized) ou « 403 Interdit » (Forbidden)) conformément au document [RFC2617].
Le protocole de publication Atom étant fondé sur HTTP est donc soumis aux considérations de sécurité énoncées à la section 15 du document [RFC2616].
Les menaces listées dans cette section s'appliquent à beaucoup de protocoles fonctionnant sous HTTP. Le groupe de travail Atompub a conclu que la protection offerte avec du HTTP authentifié sous TLS (comme décrit à la section 14) suffisait pour atténuer nombre de problèmes exposés par les attaques listées dans cette section.
Les mises en œuvre du protocole de publication Atom dans les serveurs doivent prendre les précautions nécessaires afin de s'assurer que des clients malveillants ne puissent pas consommer en excès les ressources du serveur (unité centrale, mémoire, disque, etc.)
Les mises en œuvre du protocole de publication Atom dans les serveurs sont exposées aux attaques par reproduction (replay attacks). En particulier, cette spécification ne définit aucun moyen de détecter les requêtes en double (duplicate requests). Les requêtes en double accidentelles sont impossibles à distinguer des attaques par reproduction volontaires et malveillantes.
Les mises en œuvre du protocole de publication Atom sont exposées à diverses attaques par usurpation d'identité (spoofing attacks). Des clients malveillants peuvent envoyer des entrées Atom contenant des informations inexactes n'importe où dans le document.
Les documents de fil et d'entrée Atom peuvent contenir des entités externes XML, comme défini à la section 4.2.2
de [REC-xml]. Les mises en œuvre Atom ne sont pas obligées de charger des entités externes.
Les entités externes sont exposées aux mêmes préoccupations sécuritaires que n'importe quelle exploitation de réseau et peuvent
modifier la sémantique d'un document Atom. Les mêmes problèmes existent pour les ressources liées par des éléments Atom tels que
atom:link et atom:content.
Les documents d'entrée et de fil Atom peuvent contenir des signatures numériques XML [REC-xmldsig-core] et peuvent être chiffrés en utilisant XML Encryption [REC-xmlenc-core] comme spécifié à la section 5 de [RFC4287]. Le traitement des signatures et des éléments chiffrés dans les documents Atom est expliqué aux sections 5 et 6.3 de [RFC4287].
Ni les serveurs ni les clients n'ont l'obligation de gérer le chiffrement et la signature numérique des entrées et des fils, bien qu'il se peuve que dans certaines installations les clients ou les serveurs imposent la signature ou le chiffrement des documents échangés dans le protocole Atom.
Parce que les serveurs peuvent (et sont parfois prévus pour) modifier le contenu d'un document d'entrée avant de le publier, les signatures au sein d'une entrée ne seront vraisemblablement utiles qu'au serveur auquel l'entrée est envoyée. Les clients ne peuvent pas supposer que la signature sera valide vue par un tiers, ou même que le serveur publiera la signature du client.
Un serveur peut enlever les signatures appliquées par les clients, enlever les signatures appliquées par les clients puis signer à nouveau avec sa propre clé publique, ou sursigner une entrée avec sa propre clé publique. La signification auprès d'un tiers d'une signature appliquée par un serveur est la même que celle d'une signature par quiconque, comme décrit dans le document [RFC4287]. Il est RECOMMANDÉ pour le serveur, sachant qu'il a changé une partie d'un document d'entrée qui était signé par le client, qu'il enlève cette signature avant de publier l'entrée pour prévenir les tentatives de tiers d'interpréter une signature qui ne peut pas être validée.
Les mises en œuvre du protocole de publication Atom gèrent les adresses URI et les adresses IRI. Cf. la section 7 de [RFC3986] et la section 8 de [RFC3987] pour les considérations de sécurité liées à leur traitement et leur utilisation.
Le protocole de publication Atom laisse au serveur le contrôle de la création des adresses URI. L'utilisation des données fournies par le client pour créer de nouvelles adresses URI est soumise aux mêmes préoccupations que celles décrites dans la prochaine section.
Les documents de fil et d'entrée Atom peuvent contenir une grande variété de types de contenu susceptibles d'être exécutables dans certains contextes. Des clients malveillants pourraient essayer d'attaquer les serveurs et les autres clients en injectant du code dans les ressources d'entrée ou de média d'un document de collection.
On recommande vivement pour les mises en œuvre de serveurs de vérifier que le contenu fourni par un client est sûr avant acceptation, traitement ou publication. Dans le cas de HTML, l'expérience montre que la vérification fondée sur une liste blanche (white liste) de contenus acceptables est plus efficace qu'une liste noire de contenus interdits.
On peut trouver d'autres informations à propos de la sûreté du contenu XHTML et HTML à la section 8.1 de [RFC4287].
Cette spécification emploie deux nouveaux types de média conformes à la procédure d'enregistrement (registry mechanism) décrite dans le document [RFC4288], une nouvelle en-tête de message conforme à la procédure d'enregistrement décrite dans le document [RFC3864] et deux nouvelles relations de lien conforme à la procédure d'enregistrement décrite dans le document [RFC4287].
application/atomcat+xml"Un document de catégorie du protocole de publication Atom, sérialisé en tant que XML 1.0, peut être identifié par le type de média suivant :
application/atomsvc+xml"Un document de service du protocole de publication Atom, sérialisé comme XML 1.0, peut être identifié par le type de média suivant :
Slugedit"atom:entry,
on peut utiliser l'adresse IRI de l'attribut href pour récupérer, mettre à jour et supprimer la ressource
représentée par cette entrée.edit-media"atom:entry,
on peut utiliser l'adresse IRI de l'attribut href pour récupérer, mettre à jour et supprimer la
ressource de média associée à cette entrée.L'IANA a ajouté une référence à cette spécification dans l'enregistrement du type de média "application/atom+xml".
Le contenu et les concepts de ce document sont un produit de la communauté Atom et du groupe de travail Atompub.
Cette annexe est informative.
Le schéma Relax NG exclut explicitement les éléments dans l'espace de noms du protocole Atom qui ne sont pas définis dans cette révision de la spécification. Les exigences pour les processeurs compatibles avec le protocole Atom rencontrant un tel balisage sont données aux sections 6.2 et 6.3 de [RFC4287].
Le schéma des documents de service :
# -*- rnc -*- # RELAX NG Compact Syntax Grammar for the Atom Protocol
namespace app = "http://www.w3.org/2007/app"
namespace atom = "http://www.w3.org/2005/Atom"
namespace xsd = "http://www.w3.org/2001/XMLSchema"
namespace xhtml = "http://www.w3.org/1999/xhtml"
namespace local = ""
start = appService
# common:attrs
atomURI = text
appCommonAttributes =
attribute xml:base { atomURI }?,
attribute xml:lang { atomLanguageTag }?,
attribute xml:space {"default"|"preserved"}?,
undefinedAttribute*
atomCommonAttributes = appCommonAttributes
undefinedAttribute = attribute * - (xml:base | xml:space | xml:lang
| local:*) { text }
atomLanguageTag = xsd:string {
pattern = "([A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*)?"
}
atomDateConstruct =
appCommonAttributes,
xsd:dateTime
# app:service
appService =
element app:service {
appCommonAttributes,
( appWorkspace+
& extensionElement* )
}
# app:workspace
appWorkspace =
element app:workspace {
appCommonAttributes,
( atomTitle
& appCollection*
& extensionSansTitleElement* )
}
atomTitle = element atom:title { atomTextConstruct }
# app:collection
appCollection =
element app:collection {
appCommonAttributes,
attribute href { atomURI },
( atomTitle
& appAccept*
& appCategories*
& extensionSansTitleElement* )
}
# app:categories
atomCategory =
element atom:category {
atomCommonAttributes,
attribute term { text },
attribute scheme { atomURI }?,
attribute label { text }?,
undefinedContent
}
appInlineCategories =
element app:categories {
attribute fixed { "yes" | "no" }?,
attribute scheme { atomURI }?,
(atomCategory*,
undefinedContent)
}
appOutOfLineCategories =
element app:categories {
attribute href { atomURI },
undefinedContent
}
appCategories = appInlineCategories | appOutOfLineCategories
# app:accept
appAccept =
element app:accept {
appCommonAttributes,
( text? )
}
# Simple Extension
simpleSansTitleExtensionElement =
element * - (app:*|atom:title) {
text
}
simpleExtensionElement =
element * - (app:*) {
text
}
# Structured Extension
structuredSansTitleExtensionElement =
element * - (app:*|atom:title) {
(attribute * { text }+,
(text|anyElement)*)
| (attribute * { text }*,
(text?, anyElement+, (text|anyElement)*))
}
structuredExtensionElement =
element * - (app:*) {
(attribute * { text }+,
(text|anyElement)*)
| (attribute * { text }*,
(text?, anyElement+, (text|anyElement)*))
}
# Other Extensibility
extensionSansTitleElement =
simpleSansTitleExtensionElement|structuredSansTitleExtensionElement
extensionElement = simpleExtensionElement |
structuredExtensionElement
undefinedContent = (text|anyForeignElement)*
# Extensions
anyElement =
element * {
(attribute * { text }
| text
| anyElement)*
}
anyForeignElement =
element * - app:* {
(attribute * { text }
| text
| anyElement)*
}
atomPlainTextConstruct =
atomCommonAttributes,
attribute type { "text" | "html" }?,
text
atomXHTMLTextConstruct =
atomCommonAttributes,
attribute type { "xhtml" },
xhtmlDiv
atomTextConstruct = atomPlainTextConstruct | atomXHTMLTextConstruct
anyXHTML = element xhtml:* {
(attribute * { text }
| text
| anyXHTML)*
}
xhtmlDiv = element xhtml:div {
(attribute * { text }
| text
| anyXHTML)*
}
# EOF
Le schéma des documents de catégorie :
# -*- rnc -*- # RELAX NG Compact Syntax Grammar for the Atom Protocol
namespace app = "http://www.w3.org/2007/app"
namespace atom = "http://www.w3.org/2005/Atom"
namespace xsd = "http://www.w3.org/2001/XMLSchema"
namespace local = ""
start = appCategories
atomCommonAttributes =
attribute xml:base { atomURI }?,
attribute xml:lang { atomLanguageTag }?,
undefinedAttribute*
undefinedAttribute = attribute * - (xml:base | xml:lang | local:*) {
text }
atomURI = text
atomLanguageTag = xsd:string {
pattern = "([A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*)?"
}
atomCategory =
element atom:category {
atomCommonAttributes,
attribute term { text },
attribute scheme { atomURI }?,
attribute label { text }?,
undefinedContent
}
appInlineCategories =
element app:categories {
attribute fixed { "yes" | "no" }?,
attribute scheme { atomURI }?,
(atomCategory*,
undefinedContent)
}
appOutOfLineCategories =
element app:categories {
attribute href { atomURI },
(empty)
}
appCategories = appInlineCategories | appOutOfLineCategories
# Extensibility
undefinedContent = (text|anyForeignElement)*
anyElement =
element * {
(attribute * { text }
| text
| anyElement)*
}
anyForeignElement =
element * - atom:* {
(attribute * { text }
| text
| anyElement)*
}
# EOF
Copyright (C) The IETF Trust (2007).
This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.
This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.