Le service d'annotations du CDS

Présentation

Le service d'annotations du CDS a été mis en place afin de pouvoir annoter les données contenues dans les différents services (Aladin, Simbad et VizieR). Il se présente sous forme de Web service orienté REST (REpresentationnal State Transfert) :

• le protocole HTTP est utilisé tel quel sans sur-couche
• des URI logiques permettent d'interagir avec le service
• la négociation de contenu permet au client de récupérer les données sous différents formats parmi html, xml, json et rss
• les codes d'erreurs HTML sont utilisés pour renvoyer des erreurs au client

Opérations possibles

Ajouter une annotation

• URL : http://serveur/annotations/new
• Méthode : POST
• Paramètres :
  • parentId : identifiant de l'annotation parente de celle-ci (gestion du threading), -1 si aucun parent
  • userId : identifiant du propriétaire du commentaire
  • context : le contexte du commentaire
  • element : l'élément concerné pour le contexte donné
  • isErrorNotification : précise s'il s'agit d'une notification d'erreur
  • text : le texte du commentaire
• Négociation de contenu : text/html, text/xml et application/json
• Retour :
  • html : redirection vers la page permettant de visualiser les commentaires
  • xml et json : l'identifiant du commentaire créé dans le format voulu

Récupérer un formulaire pour ajouter une annotation

• URL : http://serveur/annotations/[context]/[element]/new
• Méthode : GET
• Retour : un fichier html contenant un formulaire permettant d'ajouter une annotation pour le context [context] et l'élément [element]

Récupérer les annotations pour un context et un élément donnés

• URL : http://serveur/annotations/[context]/[element]
• Méthode : GET
• Paramètres :
  • nb : spécifie le nombre maximum d'annotations que l'on veut récupérer
  • withPrivate : si true, précise que l'on veut aussi récupérer les annotations privées
  • requesterId : l'identifiant de l'utilisateur effectuant la requète, qui doit être dans le goupe admin si le paramètre withPrivate est à true
• Négociation de contenu : text/html, text/xml et application/json
• Retour :
  • html : une page html permettant de visualiser les annotations pour le context [context] et l'élément [element]
  • json ou xml : la liste des annotations dans le format voulu
  • rss : en ajoutant /rss à la fin de l'URL, il est possible de récupérer le flux rss correspondant aux dernières annotations pour le context [context] et l'élément [element]
• Note : en omettant l'élément et/ou le context dans l'url, il est possible d'élargir le champs d'action de la requète (par exemple, http://serveur/annotations renverra toutes les annotations présentes dans la base)

Récupérer une annotation précise

• URL : http://serveur/annotations/[identifiant]
• Méthode : GET
• Négociation de contenu : text/html, text/xml et application/json
• Retour :
  • html : une page html permettant de visualiser l'annotation [identifiant](avec ses éventuels fils ou son parent)
  • json ou xml : l'annotation dans le format voulu

Récupérer les annotations faites par un utilisateur

• URL : http://serveur/annotations/byUser/[username]
• Méthode : GET
• Paramètres :
  • nb : spécifie le nombre maximum d'annotations que l'on veut récupérer
  • withPrivate : si true, précise que l'on veut aussi récupérer les annotations privées
  • requesterId : l'identifiant de l'utilisateur effectuant la requète, qui doit être dans le goupe admin si le paramètre withPrivate est à true
• Négociation de contenu : text/html, text/xml et application/json
• Retour :
  • html : une page html permettant de visualiser les annotations faites par l'utilisateur [username]
  • json ou xml : la liste des annotations dans le format [format]
  • rss : en ajoutant /rss à la fin de l'URL, il est possible de récupérer le flux rss correspondant aux dernières annotations faites par l'utilisateur [username]

Récupérer le nombre d'annotations pour un context et un élément donnés

• URL : http://serveur/annotations/[context]/[element]/nb
• Méthode : GET
• Paramètres :
  • withPrivate : si true, précise que l'on veut aussi prendre en compte les annotations privées
  • filter : un filtre peut être ajouté permettant de ne prendre en compte que certaines annotations. Sa valeur est une liste de mots clés séparés par des virgules, parmi : "archived", "errorNotification", "parent", avec comme signification :
    • archived : les annotations archivées
    • errorNotification : les annotations de type notification d'erreur
    • parent : les annotations de niveau 1 (les réponses sont exclues)
• Négociation de contenu : text/xml et application/json
• Retour : le nombre d'annotations dans le format voulu

Supprimer une annotation

• URL : http://serveur/annotations/[identifiant]/delete
• Méthode : POST
• Paramètres :
  • requesterId : identifiant de l'utilisateur exécutant la commande (il doit être dans le groupe admin)
• Négociation de contenu : text/xml et application/json
• Retour : un message donnant le statut de l'opération (succès ou échec) dans le format voulu

Mettre à jour une annotation

• URL : http://serveur/annotations/edit
• Méthode : POST
• Paramètres :
  • annotationId : identifiant de l'annotation à mettre à jour
  • text : nouveau texte de l'annotation
  • requesterId : identifiant de l'utilisateur exécutant la commande (il doit être dans le groupe admin)
• Négociation de contenu : text/xml et application/json
• Retour : un message donnant le statut de l'opération (succès ou échec) dans le format voulu

Récupérer la clé de sécurité

• URL : http://serveur/annotations?action=getSecurityKey
• Méthode : GET
• Paramètres :
  • requesterId : identifiant de l'utilisateur exécutant la commande (il doit être dans le groupe admin)
• Négociation de contenu : text/xml et application/json
• Retour : la clé de sécurité de type AES encodée en base 64, dans le format voulu

-- BriceGassmann - 01 Jul 2009