Wiki Navigation

Error: Failed to load processor TracNav

No macro or processor named 'TracNav' found

English

This page NeedsWikification.

BlogMarks.net : Spécification de l'API

Ce document décrit l'implantation de l'API Atom dans blogmarks.

L'API Atom n'étant pas finalisée, les informations fournies dans ce document ne sont qu'à titre indicative. L'API de blogmarks.net peut changer d'içi la version 1.0.

Version

Ceci est la version 0.1 de ce document.

Introduction

Cette API est basée sur la spécification 09 de l'API Atom.

The AtomAPI is an application level protocol for publishing and editing web resources. The protocol at its core is the HTTP transport of Atom formatted representations.

Terminologie Atom

Feed Atom: C'est un ensemble d'entrées Atom, regroupées de façon logique.
Entrée Atom: Une partie d'un feed Atom qui représente une ressource.
PostURI: C'est un URI permettant de créer de nouvelles ressources. On y POSTera des ressources au format atom pour les enregistrer sur le serveur.
EditURI: C'est un URI utilisé pour modifier/récupérer ou supprimer une ressource. Chaque ressource créée sur le serveur possédera un URI de ce type.
FeedURI: C'est un URI pour récupérer un ensemble de ressources regroupées dans un feed.

Dans blogmarks.net sont manipulées deux types de ressources : les blogmarks et les tags. Vous pouvez vous référer à la spécification des formats XML pour une description détaillée de ces données.

L'architecture REST

L'API Atom a été développé dans un souci de respect de l'architecture REST. Cette architecture préconise un ensemble de règles simples pour faciliter le travail du développeur. L'idée de base étant d'utiliser correctement les verbs du protocole HTTP : GET, PUT, POST et DELETE principalement. De nombreux articles et tutoriels existent sur ce sujet.

Authentification

Pour créer, modifier ou supprimer un blogmark ou modifier ses tags privés un utilisateur doit être authentifié par le serveur. Nous avons implanté l'authentification préconisée dans l'article Atom Authentication de Mark Pilgrim.

Les requêtes qui nécessitent une authentification doivent posséder deux en-têtes HTTP supplémentaires :

Authorization: WSSE profile="UsernameToken"
X-WSSE: UsernameToken Username="bob", PasswordDigest="quR/EWLAV4xLf9Zqyw4pDmfV9OY=", 
        Nonce="d36e316282959a9ed4c89851497a717f", Created="2003-12-15T14:43:07Z"

Username : Login blogmarks de l'utilisateur
PasswordDigest : digest généré côté client
Nonce : Chaîne aléatoire utilisée pour générer le digest
Created : Timestamp utilisé également pour générer le digest

Vous pourrez trouver un exemple d'implantation de ce mécanisme d'authentification dans les exemples d'utilisation de l'API.

Les URIs

La ressource principale de blogmarks.net est le blogmark. Tout utilisateur inscrit sur blogmarks.net et authentifié peut créer des blogmarks sur le serveur. Il peut également récupérer des descriptions Atom de tags publics ou créer/modifier/supprimer ses tags privés.

Les URIs des ressources dans blogmarks.net
Type de la ressource	PostURI (méthodes acceptées)	EditURI	FeedURI
blogmark	http://api.blogmarks.net/?object=Mark (POST)	http://api.blogmarks.net/?object=Mark&id=<#mark> (GET, PUT, DELETE)	http://api.blogmarks.net/?object=MarksList (GET)
tag public		http://api.blogmarks.net/?object=Tag&id=<tag> (GET)	http://api.blogmarks.net/?object=TagsList (GET)
tag privé	http://api.blogmarks.net/?object=Tag&author=<login> (POST)	http://api.blogmarks.net/?object=Tag&author=<login>&id=<tag> (GET, PUT, DELETE)	http://api.blogmarks.net/?object=TagsList (GET)

Pour effectuer des recherches, le client doit effectuer une requête de type GET sur un des FeedURI précédents. Sans paramètre, le FeedURI des marks renvoit les 30 derniers marks publics publiés sur le serveur. Le FeedURI des tags renvoit lui, par défaut, les 30 tags les plus populaires.

Paramètres possibles pour la recherche de marks
Nom	Valeurs possibles	Description	Valeur par défaut
last	-1, 1, 2, ...	Limite le nombre de résultat. -1 = pas de limitation	30
offset	0, 1, ...	Indice du premier résultat. Permet de naviguer entre les feeds.	0
search	string	Effectue une recherche globale (textuelle + tags) dans les blogmarks.
tags	string	Recherche les blogmarks contenant les tags indiqués (*).
private_tags	string	Recherche les blogmarks contenant les tags privés indiqués (*).
related	regexp	Recherche par regexp dans les liens blogmarkés.
author	string	Limiter la recherche aux marks d'un utilisateur.
private	true \| false	Indique s'il on veut les marks privés dans le feed résultat.	false
month	01, 02, ..., 11, 12	Accompagné du paramètre year, il permet de récupérer les marks postés le mois indiqué.
year	année exprimée sur 4 chiffres (ex: 2005)	S'il est accompagné du paramètre 'month', il permet de spécifier le mois recherché. Sinon permet de ne garder que les blogmarks postés l'année indiquée.
out	rss	Le format de sortie du feed sera en RSS 1.0.
level	1, 2, ...	On ne récupère que les marks dont le lien n'a été ajouté que par au moins 'level' utilisateurs.
order_by	issued\|modified\|created\|popularity	Permet d'ordonner les résultats.	issued
order_type	asc\|desc	Ordre croissant ou décroissant.	desc

* : Pour indiquer plusieurs tags il suffit de les séparer par des espaces. S'il on cherche des tags constitués de plusieurs mots, il faut entourer ce tag de guillemets doubles.

Paramètres possibles pour la recherche de tags
Nom	Valeurs possibles	Description	Valeur par défaut
last	-1, 1, 2, ...	Limite le nombre de résultat. -1 = pas de limitation	30
offset	0, 1, ...	Indice du premier résultat. Permet de naviguer entre les feeds.	0
title	string	Effectue une recherche textuelle dans le titre des tags.
summary	string	Effectue une recherche textuelle dans la description des tags.
author	string	Limiter la recherche aux tags privés de l'utilisateur.
private	true \| false	Indique s'il on veut les tags privés dans le feed résultat.	false
user	string	Limiter la recherche aux tags utilisés par le login indiqué.
minPopularity	1, 2, ...	Ne renvoit que les tags qui ont été utilisés plus de n fois par les utilisateurs.

Les URIs cool

Pour faciliter la saisie des URIs les plus utilisées nous avons mis en place des URIs simples qui sont redirigées vers les URIs génériques avec les paramètres. Ces URIs sont les suivantes :

http://api.blogmarks.net/rss/marks: Récupérer la liste des 30 derniers marks au format RSS
http://api.blogmarks.net/atom/marks ou http://api.blogmarks.net/marks: Récupérer la liste des 30 derniers marks au format Atom
http://api.blogmarks.net/rss/user/<login>: Récupérer la liste des 30 derniers marks d'un utilisateur au format RSS
http://api.blogmarks.net/atom/user/<login> ou http://api.blogmarks.net/user/<login>: Récupérer la liste des 30 derniers marks d'un utilisateur au format Atom
http://api.blogmarks.net/rss/user/<login>/tag/<tag(s)>: Récupérer la liste des 30 derniers marks d'un utilisateur, contenant un ou plusieurs tags, au format RSS
http://api.blogmarks.net/user/<login>/tag/<tag(s)> ou http://api.blogmarks.net/atom/user/<login>/tag/<tag(s)>: Récupérer la liste des 30 derniers marks d'un utilisateur, contenant un ou plusieurs tags, au format Atom
http://api.blogmarks.net/rss/tag/<tag(s)>: Récupérer la liste des 30 derniers marks, contenant un ou plusieurs tags, au format RSS
http://api.blogmarks.net/tag/<tag(s)> ou http://api.blogmarks.net/atom/tag/<tag(s)>: Récupérer la liste des 30 derniers marks, contenant un ou plusieurs tags, au format Atom
http://api.blogmarks.net/rss/search/<word(s)>: Récupérer la liste des 30 derniers marks, contenant le texte recherché, au format RSS
http://api.blogmarks.net/search/<word(s)> ou http://api.blogmarks.net/atom/search/<word(s)>: Récupérer la liste des 30 derniers marks, contenant le texte recherché, au format Atom
http://api.blogmarks.net/marks/<#mark>: EditURI d'un mark
http://api.blogmarks.net/tags/<tag>: EditURI d'un tag
http://api.blogmarks.net/user/ Voir aussi : Fr/DeveloperDocs, Fr/AtomApiXmlSpec

Download in other formats:

Plain Text