Le protocole REST

Présentation

Les informations stockées sur le service Blogmarks sont également disponibles via une interface REST.

Cette interface suit deux "standards" :

Toutes les autres interactions suivent le style d'architecture REST.

Généralités

Encodage

Blogmarks ne supporte que l'encodage utf-8. Aucune conversion ni contrôle n'est fait. Toutes les données envoyées doivent donc être en utf-8.

Authentification

Blogmarks supporte les types d'authentification suivants :

  • HTTP basique
  • Cookies
  • Digest

Gestion du cache

Un client du service Blogmarks devrait gérer un cache. Pour contrôler ce cache, les en-têtes HTTP suivantes sont renvoyées à chaque requête :

  • Last-Modified : Date de dernière modification de la ressource
    • C'est un validateur faible. Cette date correspond à la date de dernière modification majeure. Par exemple, si un ancien mark est supprimée d'un feed, la date de dernière modification du feed ne change pas. La date de dernière modification d'un feed est la date de la dernière publication d'un mark dans ce feed.
  • ETag : Etag
    • C'est un validateur fort. L'ETag d'un feed change dès qu'il y a une modification apportée dans son contenu (suppression d'un mark, modification d'un mark, ...). L'ETag d'un feed se base sur toutes les dates de dernière modification des marks qu'il contient.

Le protocole de publication Atom

Le protocole de publication des ressources sur Blogmarks suit la spécification Atom Publishing Protocol 09.

Les différents types de ressources et les méthodes HTTP disponibles sont listés dans le tableau suivant.

URI Méthode HTTP Description
http://rest.blogmarks.net/service-desc GET Retourne le document d'introspection Atom
http://rest.blogmarks.net/user/{username}/marks GET Retourne le feed Atom des marks d'un utilisateur.
POST Ajoute un mark à la collection.
DELETE Supprime tous les marks de l'utilisateur.
http://rest.blogmarks.net/user/{username}/mark/{id} GET Retourne la réprésentation d'un mark au format Atom.
PUT Met à jour le mark.
DELETE Supprime le mark.
http://rest.blogmarks.net/user/{username}/friends/marks GET Retourne le feed Atom des marks des amis de l'utilisateur.
http://rest.blogmarks.net/marks GET Retourne le feed Atom des marks publics de tous les utilisateurs.
http://rest.blogmarks.net/link/{hash}/marks GET Retourne le feed Atom des marks sur le lien.
http://rest.blogmarks.net/link/{hash}/comments GET Retourne le feed Atom des commentaires sur le lien.
POST Poste un commentaire sur le lien.
http://rest.blogmarks.net/link/{hash}/comment/{id} GET Retourne la représentation Atom d'un commentaire.

Le document d'introspection

<?xml version="1.0" encoding="utf-8"?>
<service xmlns="http://purl.org/atom/app#">
  <workspace title="BlogMarks Service" > 
    <collection title="Public Marks" href="http://rest.blogmarks.net/marks"/>
  </workspace>
</service>

Les formats Atom

Mark

Un mark est vu comme une entrée Atom par le protocole de publication. La sémantique des propriétés d'un mark est donnée dans le tableau suivant.

Les préfixes sur les propriétés indiquent les espaces de nom XML :

  • atom : http://www.w3.org/2005/Atom
  • app : http://purl.org/atom/app#
  • bm : http://blogmarks.net/ns
Nom Description Modifiable par l'utilisateur
atom:id Identifiant unique du mark, ne changera pas.
atom:title Le titre du mark. x
atom:link[@rel=related] Le lien décrit par le bookmark. x
atom:link[@rel=alternate] Le lien vers la représentation HTML du mark (sur l'interface web).
atom:published La date de création du mark. x
atom:updated La date de dernière modification du mark.
atom:author Auteur du mark.
atom:link[@rel=via] Referer lorsque l'utilisateur a ajouté le lien à ses marks. x
atom:link[@rel=enclosure] Url du screenshot du lien que décrit le mark. x
atom:category Tag associé au mark. x
atom:content Description du lien posté. x
app:link[@rel=edit] Indique que le mark est éditable et donne l'URI pour le modifier ou le supprimer.
bm:link[@rel=comments] Url du feed Atom des commentaires sur le lien du mark.
bm:isPrivate Indique si le mark est privé ou non. x

Commentaire

Nom Description
atom:id Identifiant unique du commentaire, ne changera pas.
atom:link[@rel=related] Le lien sur lequel est le commentaire.
atom:link[@rel=alternate] Le lien vers la représentation HTML du commentaire (sur l'interface web).
atom:published La date de publication du commentaire.
atom:author Auteur du commentaire
atom:content Contenu du commentaire

Les autres types de ressources

Blogmarks met à disposition des développeurs d'autres types de ressources mais toujours selon une architecture REST.

Les tags

Les tags permettent aux utilisateurs de classer leurs marks.

Deux types de ressources

Collection de tags :

  • http://rest.blogmarks.net/tags : tags publics
  • http://rest.blogmarks.net/user/{username}/tags : tags utilisés par username

Un tag :

  • http://rest.blogmarks.net/tags/{id} dont on peut récupérer une représentation par la méthode GET.

Format

@TBD@

Références