Fr/AtomApiTutorial - blogmarks.net - Trac

Wiki Navigation

Error: Failed to load processor TracNav

No macro or processor named 'TracNav' found

This document is also available in English.

GET & Authentification

Pour parcourir les liens publics postés sur Blogmarks.net, il suffit juste de rapatrier l'url

http://api.blogmarks.net/marks

Par défaut, les 30 derniers liens postés sur Blogmarks.net sont envoyés.

ce qui correspond aux paramètres suivants :

last : 30
order_type : DESC
order_by : created

et à URL suivante :

http://api.blogmarks.net/marks?last=30&order_type=DESC&order_by=created

Ainsi vous pouvez récupérer les 10 liens les plus populaires, en tapant cette URL :

http://api.blogmarks.net/marks?last=10&order_by=popularity

Ecrivons notre première requête HTTP et cherchons le dernier lien ajouté:

GET /marks?last=1 HTTP/1.0
Host: api.blogmarks.net
Accept: application/atom+xml

La réponse du serveur :

HTTP/1.1 200 OK
Date: Mon, 07 Mar 2005 19:32:10 GMT
Server: Apache/1.3.26 (Unix) Debian GNU/Linux PHP/4.3.9-1.dotdeb.3
X-Powered-By: PHP/4.3.9-1.dotdeb.3
Content-length: 1293
Connection: close
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<feed
version="draft-ietf-atompub-format-05:do not deploy"
xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-05"
xmlns:bm="http://api.blogmarks.net/ns#">
<head>
	<title>Last public marks</title>
	<link rel="alternate" type="application/xhtml+xml" href="?last=1"/>
	<link rel="next" type="application/atom+xml" href="http://api.blogmarks.net/marks?last=1&amp;offset=1&amp;order_type=DESC&amp;order_by=created"/>
	<updated>2005-03-07T20:23:04Z</updated>
</head>
<entry>
	<id>tag:blogmarks.net,2005:marks,31171</id>
	<title type="TEXT">Kevin Kelly -- Cool Tools:Wall Full of Whiteboard</title>
	<link rel="related" href="http://www.kk.org/cooltools/archives/000679.php" type="text/html"/>
	<link rel="alternate" href="http://blogmarks.net/user/delicious.popular/archives/2005/03/#mark31171" type="application/xhtml+xml" title="Kevin Kelly -- Cool Tools:Wall Full of Whiteboard"/>
	<link rel="image" href="http://www.blogmarks.net/screenshots/2005/03/07/2d3eb782512a6aff2540f74a0a32bd3d.png" type="image/png"/>
	<updated>2005-03-07T20:23:04Z</updated>
	<published>2005-03-07T20:23:04Z</published>
	<author><name>delicious.popular</name></author>
	<edit>http://api.blogmarks.net/atom/marks/31171</edit>
	<bm:created>2005-03-07T20:23:04Z</bm:created>
</entry>
</feed>

Si vous voulez écrire tous ceci dans un script, nous vous recommandons d'utiliser une librairie HTTP comme par exemple Pear HTTP:Request (dans le cas où vous utilisez PHP ;)

<?php

require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://api.blogmarks.net/marks?last=1");
$req->addHeader("Accept", 'application/atom+xml');

$response = $req->sendRequest();

if (PEAR::isError($response)) {
	echo $response->getMessage();
} else {
	$code = $req->getResponseCode();
	switch ( $code ) {
	  case 200:
	    $xml = $req->getResponseBody();
	    // Handle the resulting Atom response here
	    echo $xml;
	    break;
	  default:
	    echo $code . " Error\n";
	    break;
	}
	
}

?>

Pour votre curiosité, dans vanilla PHP, vous pouvez écrire ceci (script trés simple, sans gestion d'erreur)

<?php

$request  = 'GET /marks?last=1 HTTP/1.0' . "\n";
$request .= 'Host: api.blogmarks.net' . "\n";
$request .= 'Accept: application/atom+xml' . "\n";
$request .= "\n";

$fp = fsockopen('api.blogmarks.net', 80, $errno, $errstr, 30);

fputs($fp,$request);

$response = '';
while ( !feof ( $fp ) ) {
	$line = fgets ($fp, 128);
	$response .= $line;
}
fclose($fp);

echo $response;

?>

Maintenant, imaginons que vous voulez rapatrier vos liens et tags privés. Ceci nécessite une authentification. Comme conseillé dans le tutorial d'authentification ATOM par Mark Pilgrim, nous emploierons l'authentification WSSE . Pour plus d'explication sur le sujet de l'authentification WSSE, lire le tutorial de Mark Pilgrim).

Nous commencons avec 4 variables :

$Username : znarf
$Password : foo
$Nonce (a cryptographically random string ) : 15253654
$CreationTimestamp (the current time in W3CDTF format) : 2004-03-08T17:11:42Z

Dans notre implémentation, nous utilisons le hash md5 sur le password. Si vous avez le password original hashez le, sinon utilisé celui hashé.

Ainsi :

$PasswordHash = md5( $Password );

Créer le "digest" du password

$PasswordDigest = Base64 ( SHA1 ( $Nonce + $CreationTimestamp + $PasswordHash ) )

Il suffit donc d'ajouter deux lignes à l'en-tête HTTP et nous voilà authentifier. A noter le paramètre private est mis à TRUE pour pouvoir rapatrier les liens et tags privés.

GET /marks?last=30&private=true HTTP/1.0
Host: api.blogmarks.net
Accept: application/atom+xml
Authorization: WSSE profile="UsernameToken"
X-WSSE: UsernameToken Username="$Username", PasswordDigest="$PasswordDigest", Nonce="$Nonce", Created="$CreationTimestamp"

Le code PHP correspond est le suivant:

<?php

$Username = 'znarf';
$Password = 'foo';
$Nonce = rand( 1 , 100000000000000 );
$CreationTimestamp = date('Y-m-d\Th:i:s\Z');

$PasswordHash = md5( $Password );

$PasswordDigest = base64_encode( sha1( $Nonce . $CreationTimestamp . $PasswordHash  ) );

require_once "HTTP/Request.php";

$req =& new HTTP_Request("http://api.blogmarks.net/marks?last=1");
$req->addHeader("Accept", 'application/atom+xml');
$req->addHeader('Authorization', 'WSSE profile="UsernameToken"');
$req->addHeader('X-WSSE', 'UsernameToken Username="' . $Username . '",
      PasswordDigest="' . $PasswordDigest . '", Nonce="' . $Nonce . '", Created="' . $CreationTimestamp . '"');

$response = $req->sendRequest();

if (PEAR::isError($response)) {
	echo $response->getMessage();
} else {
	$code = $req->getResponseCode();
	switch ( $code ) {
	  case 200:
	    $xml = $req->getResponseBody();
	    // Handle the resulting Atom response here
	    echo $xml;
	    break;
	  default:
	    echo $code . " Error\n";
	    break;
	}
	
}

?>

Nous avons pris partis de traiter la gestion d'erreur avec le module PEAR mais le mieux est d'utiliser les composants prévus par le framework de votre choix.

POST : ajouter un nouveau lien

On ajoute un nouveau lien sur Blogmarks.net, en postant une entrée ATOM sur une postURI. la postURI est http://api.blogmarks.net/marks. Dans une entrée ATOM, le titre et le lien associé doivent obligatoirement être spécifié.

Premier Exemple

Nous allons voir comment créer un blogmark simple et valide. L'authentification est expliqué dans le tutorial Fr/AtomApiTutorial/Get.

Envoi du client :

POST /marks HTTP/1.0
Host: api.blogmarks.net
Accept: application/atom+xml
Content-Type: text/xml; charset=utf-8
Content-length: 267
Authorization: WSSE profile="UsernameToken"
X-WSSE: UsernameToken Username="$Username", PasswordDigest="$PasswordDigest", Nonce="$Nonce", Created="$CreationTimestamp"

<entry
  version="draft-ietf-atompub-format-05:do not deploy"
  xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-05"
  xmlns:bm="http://api.blogmarks.net/ns#">
<title>Znarf Blog</title>
<link rel="related" href="http://upian.net/znarf/blog/" />
</entry>

La réponse du serveur :

HTTP/1.1 201 Created
Date: Wed, 09 Mar 2005 11:21:03 GMT
Content-length: 811
Connection: close
Content-Type: application/atom+xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<entry
  xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-05"
  xmlns:bm="http://api.blogmarks.net/ns#>
 <id>tag:blogmarks.net,2005:marks,31523</id>
 <title type="TEXT">Znarf Blog</title>
 <link rel="related" href="http://upian.net/znarf/blog/" type="text/html"/>
 <link rel="alternate" href="http://blogmarks.net/user/znarf/archives/2005/03/#mark31523" type="application/xhtml+xml" title="Znarf Blog Test"/>
 <link rel="image" href="http://blogmarks.net/screenshots/2005/03/09/dbc0c60c8794c0ca4f2e99f10a5f2408.png" type="image/png"/>
 <updated>2005-03-09T12:21:03Z</updated>
 <author><name>znarf</name></author>
 <edit>http://api.blogmarks.net/marks/31523</edit>
 <bm:created>2005-03-09T12:21:03Z</bm:created>
</entry>

Deuxième exemple

Nous allons créer un blogmark plus aboutie.

Dans ATOM, les tags sont appelés category.
En spécifiant la balise published=0000-00-00, le blogmark devient alors privé (non publié).
La balise bm:created représente la date de publication du lien. Elle est utilisé pour trier les blogmarks chronologiquement.

POST /marks HTTP/1.0
Host: api.blogmarks.net
Accept: application/atom+xml
Content-Type: text/xml; charset=utf-8
Content-length: 535
Authorization: WSSE profile="UsernameToken"
X-WSSE: UsernameToken Username="$Username", PasswordDigest="$PasswordDigest", Nonce="$Nonce", Created="$CreationTimestamp"

<?xml version="1.0" encoding="UTF-8"?>
<entry
  version="draft-ietf-atompub-format-05:do not deploy"
  xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-05"
  xmlns:bm="http://api.blogmarks.net/ns#">
 <title>Znarf Blog</title>
 <link rel="related" href="http://upian.net/znarf/blog/" />
 <link rel="via" href="http://blogmarks.net/" />
 <summary>This blog really rox</summary>
 <category label="blog" />
 <category label="dotclear" />
 <published>0000-00-00</published>
 <bm:created>2005-03-09</bm:created>
</entry>

Le même code en PHP / Pear HTTP Request

<?php

$Username = 'znarf';
$Password = '';
$Nonce = rand( 1 , 100000000000000 );
$CreationTimestamp = date('Y-m-d\Th:i:s\Z');

$PasswordHash = md5( $Password );

$PasswordDigest = base64_encode( sha1( $Nonce . $CreationTimestamp . $PasswordHash  ) );

require_once "HTTP/Request.php";

$req =& new HTTP_Request('http://api.blogmarks.net/marks');
$req->setMethod(HTTP_REQUEST_METHOD_POST);
$req->addHeader('X-WSSE', 'UsernameToken Username="' . $Username . '", PasswordDigest="' . $PasswordDigest . '", Nonce="' . $Nonce . '", Created="' . $CreationTimestamp . '"');

$xml  =
'<?xml version="1.0" encoding="UTF-8"?>
<entry
  version="draft-ietf-atompub-format-05:do not deploy"
  xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-05"
  xmlns:bm="http://api.blogmarks.net/ns#">
 <title>Znarf Blog</title>
 <link rel="related" href="http://upian.net/znarf/blog/" />
 <link rel="via" href="http://blogmarks.net/" />
 <summary>This blog rox</summary>
 <category term="http://api.blogmarks.net/tags/" sheme="blog" />
 <category term="http://api.blogmarks.net/tags/" sheme="dotclear" />
 <published>0000-00-00</published>
 <bm:created>2005-03-09</bm:created>
</entry>';

$req->addRawPostData($xml);

$response = $req->sendRequest();

if (PEAR::isError($response)) {
    echo $response->getMessage();
} else {
    $code = $req->getResponseCode();
    switch ($code) {
    case 201:
      echo "OK\n";
      echo $req->getResponseBody();
      break;
    default:
      echo $code . " Error\n";
      break;
    }
}

?>

Bonnes pratiques

Ne pas flooder : Le Flooding est lorsque une longue liste de blogmarks est postée (plus de 5)ce qui a pour résultat de remplir la liste des derniers liens Public. Les utilisateurs (en général) n'aiment vraiment pas ça. Nous recommandons donc aux utilisateurs voulant faire de grands imports de spécifier dans la balise bm:created une date passée. Vous devez en avoir une si vous importez des liens. Sinon, nous recommandons de mettre la date courante sans spécifier l'heure <bm:created>2005-03-08Z</bm:created>

PUT : Mise à jour d'un blogmark

Pour mettre un jour un blogmark, il suffit juste de mettre une entrée ATOM sur le lien editURI.

L'editURI peut être trouvé dans les entrées ATOM et est simplement http://api.blogmarks.net/marks/$MarkID

L' authentification est expliqué dans le tutorial Fr/AtomApiTutorial/Get.

Envoi du client :

PUT /marks/31523 HTTP/1.0
Host: api.blogmarks.net
Accept: application/atom+xml
Content-Type: text/xml; charset=utf-8
Content-length: 433
Authorization: WSSE profile="UsernameToken"
X-WSSE: UsernameToken Username="$Username", PasswordDigest="$PasswordDigest", Nonce="$Nonce", Created="$CreationTimestamp"

<entry
  version="draft-ietf-atompub-format-05:do not deploy"
  xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-05"
  xmlns:bm="http://api.blogmarks.net/ns#">
 <title>Znarf Blog</title>
 <link rel="related" href="http://upian.net/znarf/blog/" />
 <summary>This blog *really* rox</summary>
 <category term="http://api.blogmarks.net/tags/" sheme="blog" />
 <category term="http://api.blogmarks.net/tags/" sheme="dotclear" />
 <category term="http://api.blogmarks.net/tags/" sheme="daily" />
 <category term="http://api.blogmarks.net/tags/" sheme="topsite" />
</entry>

Réponse du serveur :

HTTP/1.1 200 OK
Date: Wed, 09 Mar 2005 11:21:03 GMT
Content-length: 811
Connection: close
Content-Type: application/atom+xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<entry
  xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-05"
  xmlns:bm="http://api.blogmarks.net/ns#>
 <id>tag:blogmarks.net,2005:marks,31523</id>
 <title type="TEXT">Znarf Blog</title>
 <link rel="related" href="http://upian.net/znarf/blog/" type="text/html"/>
 <link rel="alternate" href="http://blogmarks.net/user/znarf/archives/2005/03/#mark31523" type="application/xhtml+xml" title="Znarf Blog"/>
 <link rel="image" href="http://blogmarks.net/screenshots/2005/03/09/dbc0c60c8794c0ca4f2e99f10a5f2408.png" type="image/png"/>
 <summary>This blog *really* rox</summary>
 <updated>2005-03-09T11:21:03Z</updated>
 <author><name>znarf</name></author>
 <edit>http://api.blogmarks.net/marks/31523</edit>
 <category term="http://api.blogmarks.net/tags/" sheme="blog" label="blog"/>
 <category term="http://api.blogmarks.net/tags/" sheme="dotclear" label="dotclear"/>
 <category term="http://api.blogmarks.net/tags/" sheme="daily" label="daily"/>
 <category term="http://api.blogmarks.net/tags/" sheme="topsite" label="topsite"/>
 <bm:created>2005-03-09T12:21:03Z</bm:created>
</entry>

Supprimer

Pour supprimer blogmark, Il suffit juste d'envoyer une requête HTTP Delete sur le lien editURI.

L'editURI peut être trouvé dans les entrées ATOM et est simplement http://api.blogmarks.net/marks/$MarkID

L' authentification est expliqué dans le tutorial Fr/AtomApiTutorial/Get.

Envoi du client :

DELETE /marks/1025 HTTP/1.0
Host: api.blogmarks.net
Authorization: WSSE profile="UsernameToken"
X-WSSE: UsernameToken Username="$Username", PasswordDigest="$PasswordDigest", Nonce="$Nonce", Created="$CreationTimestamp"

La réponse du serveur :

HTTP/1.1 200 OK
Date: Thu, 10 Mar 2005 12:10:26 GMT
Connection: close

With PHP / Pear HTTP:Request you write

<?php

$Username = 'znarf';
$Password = '';
$Nonce = rand( 1 , 100000000000000 );
$CreationTimestamp = date('Y-m-d\Th:i:s\Z');

$PasswordHash = md5( $Password );

$PasswordDigest = base64_encode( sha1( $Nonce . $CreationTimestamp . $PasswordHash  ) );

require_once "HTTP/Request.php";

$req =& new HTTP_Request('http://api.blogmarks.net/marks/1025');
$req->setMethod(HTTP_REQUEST_METHOD_DELETE);
$req->addHeader('X-WSSE', 'UsernameToken Username="' . $Username . '", PasswordDigest="' . $PasswordDigest . '", Nonce="' . $Nonce . '", Created="' . $CreationTimestamp . '"');

$response = $req->sendRequest();

if (PEAR::isError($response)) {
    echo $response->getMessage();
} else {
    $code = $req->getResponseCode();
    switch ($code) {
    case 200:
      echo "OK\n";
      break;
    default:
      echo $code . " Error\n";
      echo $req->getResponseBody();
      break;
    }
}

?>

Voir aussi : Fr/DeveloperDocs

Download in other formats:

Plain Text