API

L’API de Seenthis est en plein développement.

La méthode retenue est l’Atom Publishing Protocol. Pour une présentation :
http://www.bortzmeyer.org/5023.html.

Voici un code PHP qui, en utilisant CURL, provoque la publication d’un message sur le flux de l’auteur identifié par $login et $pass.

La connexion se fait en POST sur l’adresse https://seenthis.net/api/messages. Le protocole est obligatoirement https, pour éviter de faire circuler les mots de passe en clair sur le réseau (si vous n’envoyez pas les infos sur le port sécurisé, la connexion sera refusée).

Attention : le texte qu’on envoie n’est jamais du HTML, mais du texte brut (comme dans l’interface de Seenthis). Par convention, on préférera expédier ce texte via le summary d’ATOM. Si on n’utilise pas le summary, c’est le content qui est utilisé.

En réponse, si l’insertion a réussi, on récupère une entrée ATOM. Noter la subtilité :
summary contient le message en mode texte (nettoyé), c’est le texte qu’on voudra éventuellement modifier et réexpédier via l’API ;
content contient le message formaté, en HTML. On l’utilisera certainement, localement, pour l’affichage, mais en aucun cas on ne l’utilisera pour le réexpédier via l’API.

$login = "monlogin";
$pass = "monpass";

$message = "C'est top!\nhttp://www.seenthis.net\n\n";

// Si on modifie un message existant, mettre son identifiant 
// CURLOPT_CUSTOMREQUEST à PUT
// $id_me = "message:35";

// Si le message est une réponse
// $inreplyto = "message:34";

$xml = "
<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' 
xmlns:thr='http://purl.org/syndication/thread/1.0' 
xmlns:docs='http://schemas.google.com/docs/2007'>
<id>$id_me</id>
<summary><![CDATA[$message]]></summary>
<thr:in-reply-to ref='$inreplyto'/>
</entry>
";

$post_url = "https://seenthis.net/api/messages";

$request = curl_init(); // initiate curl object
curl_setopt($request, CURLOPT_URL, $post_url);
curl_setopt($request, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($request, CURLOPT_HEADER, 0); // set to 0 to eliminate header info from response
curl_setopt($request, CURLOPT_HTTPHEADER, array("Content-Type: application/atom+xml;type=entry"));
curl_setopt($request, CURLOPT_CUSTOMREQUEST, 'POST' );	
curl_setopt($request, CURLOPT_USERPWD, "$login:$pass");
curl_setopt($request, CURLOPT_POSTFIELDS, "$xml");

$post_response = curl_exec($request); // execute curl post and store results in $post_response
curl_close ($request); // close curl object

On doit (sauf erreur) pouvoir indiquer qu’un (nouveau) message est une réponse à un autre message, en utilisant thr:in-reply-to.

Pour modifier un message existant, indiquer son id, et passer le message HTTP en méthode PUT.

Pour l’instant, il n’y a pas la possibilité de consulter un message par l’API (qui sera en méthode GET). Ni de le supprimer (méthode DELETE). De ce fait, pour l’instant, l’API permet essentiellement d’alimenter automatiquement un compte depuis l’extérieur, mais pas réellement d’interagir avec le système.

Fonctions PHP pour exploiter directement l’API

J’ai également commencé un fichier de fonctions directement utilisables pour exploiter l’API.

function seenthis_create_message($titre, $link, $quote, $comment, $tags) {
$ret = "";
if (strlen($titre) > 0) $ret .= "$titre\n";
if (strlen($link) > 0) $ret .= "$link\n";
$ret .= "\n";

if (strlen($quote) > 0) $ret .= "❝".$quote."❞\n\n";
if (strlen($comment) > 0) $ret .= "$comment\n";

if (!is_array($tags)) {
$tags = explode(" ", $tags);
}
foreach($tags as $tag) {
$tag = trim($tag);
$tag = preg_replace(",^#,", "", $tag);
if (strlen($tag) > 0) {
$l .= "#$tag ";
}
}
if (strlen($l) > 0) $ret .= "\n$l\n";

return $ret;
}


function seenthis_create_xml($message, $id_me=0, $inreplyto=0) {
$xml = "<?xml version='1.0' encoding='UTF-8'?>\n"
."<entry xmlns='http://www.w3.org/2005/Atom' xmlns:thr='http://purl.org/syndication/thread/1.0'>\n";
if ($id_me > 0) $xml .= "<id>$id_me</id>\n";
$xml .= "<summary><![CDATA[".trim($message)."]]></summary>\n";
if ($inreplyto > 0) $xml .= "<thr:in-reply-to ref='message:$inreplyto'/>\n";
$xml .= "</entry>\n";

return $xml;
}

function seenthis_curl(https://seenthis.net/$xml, $login, $pass, $method) {
$post_url = "https://seenthis.net/api/messages";
$request = curl_init(); // initiate curl object
curl_setopt($request, CURLOPT_URL, $post_url);
curl_setopt($request, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($request, CURLOPT_HEADER, 0); // set to 0 to eliminate header info from response
curl_setopt($request, CURLOPT_HTTPHEADER, array("Content-Type: application/atom+xml;type=entry"));
curl_setopt($request, CURLOPT_CUSTOMREQUEST, $method );	
curl_setopt($request, CURLOPT_RETURNTRANSFER, true );	
curl_setopt($request, CURLOPT_USERPWD, "$login:$pass");
curl_setopt($request, CURLOPT_POSTFIELDS, "$xml");

$post_response = curl_exec($request); // execute curl post and store results in $post_response
curl_close ($request); // close curl object

return $post_response;
}


function seenthis_post($message, $login, $pass, $inreplyto=0) {
$xml = seenthis_create_xml($message, 0, $inreplyto) ;

return seenthis_curl(https://seenthis.net/$xml, $login, $pass, "POST");
}

Et pour l’utiliser :

— une fonction (totalement optionnelle, mais qui peut s’avérer pratique) seenthis_create_message, qui retourne une chaîne correspond aux habitudes de Seenthis ;

— surtout, la fonction seenthis_post pour poster ce message sur Seenthis. Particulièrement simple. Pour l’instant, ça retourne le contenu de la réponse (si ça a fonctionné, une entrée ATOM).

$login = "monlogin";
$pass = "monpass";

$message = seenthis_create_message(
"La jeunesse : sacrifiée ou enfermée ? - LeMonde.fr",
"http://www.lemonde.fr/idees/article/2011/03/17/la-jeunesse-sacrifiee-ou-enfermee_1494846_3232.html",
"Les comparaisons internationales indiquent que plus les diplômes jouent un rôle décisif dans l’accès à l’emploi, plus les élèves et leur famille pensent que l’école est le seul recours, plus les inégalités scolaires sont fortes. Ceci se comprend aisément : si l’on pense que tout se joue à l’école, il faut choisir les stratégies les plus sélectives conduisant vers les profils et les formations les plus rentables. Dès lors, au-delà des idéologies égalitaires, tout ce qui crée un écart scolaire est bon. Dans ce jeu, les familles déjà privilégiées sont gagnantes et la reproduction sociale entre les générations a toutes les chances de se renforcer. Quand je suis persuadé qu’il est juste et bon que l’école définisse ma valeur et mon mérite me donnant accès à l’emploi, il est normal que je cherche à creuser les écarts avec mes concurrents et, au bout du compte, l’école en rajoute aux inégalités.",
"Et ceci est mon commentaire...",
"#éducation #école #jeunesse #diplômes");

echo seenthis_post($message, $login, $pass);