[[TracNav(TracNav)]]
[[TOC]]
This page is also available in [wiki:Fr/AtomApiXmlSpec French].
----
= Atom ressources format description =
This document describes XML syntax for Blogmarks.net Atom ressources.
'''The blogmarks.net Atom API may change until version 1.0'''
== Version ==
This is version 0.1 of this document.
== Introduction ==
[wiki:AtomApiSpec The Blogmarks.net Atom API specification] explains how to communicate with server. This document is about the various XML syntaxes used to describe blogmarks.net ressources.
Most of the elements described below are defined by [http://www.atomenabled.org/developers/api/atom-format-spec.php the latest Atom Format specification]. In some cases, this format has been extended using XML namespaces to provide a better description of blogmarks.net ressources : '''blogmarks''' & '''tags'''.
== Blogmarks syntax ==
The blogmarks is our projects base ressource. Think of it as a bookmark with added metadata. Users can add blogmarks to the server. They can be public or private. One can add tags to blogmarks in order to sort them and therefore enable easier access.
=== Id ===
This mark's Atom identifier. It is unique and autogenerated by server at mark's creation time. It will look like {{{tag:blogmarks.net,2005:marks,432}}}. Nothing should be guessed from it and it must be kept entirely.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Forbidden || Available || ''GET'' : Available, ''PUT'' : Optional ||
=== link[@rel=related] ===
Points to blogmarked URI.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Mandatory || Available || ''GET'' : Available, ''PUT'' : Mandatory ||
=== link[@rel=alternate] ===
Points to blogmark's HTML representation
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Forbidden || Available || ''GET'' : Available, ''PUT'' : Forbidden||
=== link[@rel=image] ===
Point's to blogmarked site's screenshot.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Forbidden || Available || ''GET'' : Available, ''PUT'' : Forbidden||
=== edit ===
Points to blogmark's EditURI.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Forbidden || Available || ''GET'' : Available, ''PUT'' : Forbidden||
=== title ===
Blogmark's title.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Mandatory || Available || ''GET'' : Available, ''PUT'' : Mandatory ||
=== summary ===
Blogmark's summary.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Optional || Optional || ''GET'' : Optional, ''PUT'' : Optional ||
=== published ===
Blogmarks publication date.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
||
Can be set if client wants publication date to be different from creation date ({{{bm:created}}}). It can be set to a future date. || Available if not null || ''GET'' : Available if not null, ''PUT'' : Cf. PostURI ||
=== bm:created ===
Blogmark's creation date.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Forbidden || Available || ''GET'' : Available, ''PUT'' : Forbidden ||
=== updated ===
Blogmark's last modification date.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Forbidden || Available || ''GET'' : Available, ''PUT'' : Forbidden ||
=== author ===
Blogmark's author.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Can be set, but won't be used by server. Blogmark's owner will be logged in user. || Available || ''GET'' : Available, ''PUT'' : Optional ||
=== category ===
Tag associated to blogmark.
{{{
#!xml
}}}
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Optional || Optional || ''GET'' : Optional, ''PUT'' : Optional ||
== Syntaxe d'un tag ==
=== Id ===
C'est l'identifiant "atom" du tag. Il est unique et auto généré par le serveur lorsque le mark est créé. Il sera de la forme : 'tag:blogmarks.net,2005:tags,145'. Aucune information ne doit être déduite de ce tag et il doit être conservé dans sa totalité.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Forbidden || Available || ''GET'' : Available, ''PUT'' : Mandatory||
=== link[@rel=alternate] ===
Pointe sur la reAvailableation html du tag.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Forbidden || Available || ''GET'' : Available, ''PUT'' : Forbidden ||
=== link[@rel=image] ===
Pointe sur une image associé au tag.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Optional || Optional || ''GET'' : Optional, ''PUT'' : Optional ||
=== edit ===
Pointe sur l'EditURI du blogmark.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Forbidden || Available || ''GET'' : Available, ''PUT'' : Forbidden ||
=== title ===
Titre du tag.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Mandatory || Available || ''GET'' : Available, ''PUT'' : Mandatory ||
=== summary ===
Description du tag.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Optional || Optional || ''GET'' : Optional, ''PUT'' : Optional ||
=== published ===
Date de publication du tag.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| L'utilisateur ne pouvant créer que des tags privés, la date de publication n'a pas de sens içi ||
Optional (Toujours Available pour les tags publics) || ''GET'' : Peut être Available (Est Available pour les tags publics), ''PUT'' : Cf. PostURI||
=== bm:created ===
Date de création du tag.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Forbidden || Available || ''GET'' : Available, ''PUT'' : Forbidden ||
=== updated ===
Date de dernière modification du tag.
|| '''PostURI''' || '''FeedURI''' || '''EditURI''' ||
|| Forbidden || Available || ''GET'' : Available, ''PUT'' : Forbidden ||
== Syntaxe d'un feed ==
Un feed contient un en-tête (head) et une liste d'entrées. L'en-tête peut contenir les éléments suivants.
=== title ===
Titre du feed généré par le serveur en fonction de la requête.
=== alternate ===
Lien vers le feed correspondant de l'interface blogmarks.net.
=== link[@rel=prev] ===
Lien vers le feed précédent s'il existe. Permet de naviguer entre les réponses d'une requête.
=== link[@rel=next] ===
Lien vers le feed suivant s'il existe.
=== updated ===
La plus grande date de dernière modification des entrées du feed résultat.
== Syntaxe des messages d'erreur ==
Lorsque le serveur rencontre une erreur, il renvoit dans le corps de la réponse un message précisant cette erreur, du type :
{{{
#!xml
No user connected
}}}
----
See also : DeveloperDocs, AtomApiSpec