Waluu met à disposition une API unique pour tous les sites du Waluu Network. Le Waluu Network est le réseau de Waluu Sites accessible depuis Waluu.com, on y retrouve par exemple Knily.com, Jookees.com et Mister-Finger.com.

La documentation qui suit constitue la référence officielle de l'interface de programmation que Waluu offre à tous les développeurs.

Cette API se veut accessible, simple et rapide à mettre en oeuvre : aucune authentification n'est requise, vous pouvez l'utiliser à des fins de tests. Pour toute question : écrivez à contact@waluutwins.com, ou bien tweetez nous : @waluutwins.

Sommaire

Généralités

Caractéristiques de l'API

  • Repose sur une architecture REST .
  • Les paramètres fournis doivent utiliser l'encodage UTF-8.
  • Les données seront retournées au format XML
  • Le terme item est utilisé pour désigner la contribution d'un membre sur un Waluu Site. Par exemple, pour Jookees.com l'item est une blague.

Authentification

Les méthodes disponible par l'API en écriture requiert l'authentification de l'utilisateur. Ces méthodes concerne la création, la mise à jour et la suppression d'une ressource (les items, les commentaires et les votes sont des ressources).

Cet authentification est basé sur "HTTP Basic authentication". Vous devrez donc envoyer le login et le mot de passe de l'utilisateur pour qui vous allez réaliser l'action.
La méthode la plus simple pour envoyer le login et le mot de passe de l'utilisateur est de former vos requêtes HTTP de la manière suivante : 

http://<login>:<mot de passe>@<host>/api/...

Selon le langage de programmation utilisé vous pouvez passer ces deux paramètres par d'autres moyens, je vous invite à consulter la documentation concernant l'utilisation de "HTTP Basic authentication" pour votre langage de programmation.

Les méthodes (verbe) HTTP

Comme il s'agit d'une API REST vous devrez utiliser la bonne méthode (aussi appelé verbe) HTTP lors de l'envoi de votre requête. Celle-ci est précisé pour chaque requêtes.

Cependant il est possible que votre langage de programmation ne vous permet pas d'utiliser les méthodes "DELETE" et "PUT".
Dans ce cas vous pourrez utiliser à la place la méthode "POST" et spécifier en paramètre _method=DELETE pour simuler la méthode DELETE et _method=PUT pour simuler la méthode PUT.

Ainsi l'appel suivant permet une mise à jour d'un item grâce à la méthode HTTP "PUT" : 

PUT -d "link_title=changement de titre" http://login:password@knily.com/api/items/60.xml

Peut être réalisé en utilisant la méthode HTTP "POST" et le paramètre "_method=put" :

POST -d "_method=put"  -d "link_title=Changement de titre" http://login:password@knily.com/api/items/60.xml

Lister les items (items.xml)

Retourne par défaut les items de la page d'accueil d'un Waluu Site donné.

URL d'appel

GET http://<hôte>/api/items.xml

<hôte> : Correspond au Waluu Site sur lequel on effectue la recherche. Exemple : www.jookees.com.

Cette méthode peut prendre des paramètres supplémentaires pour filtrer les résultats retournés. Les paramètres s'ajoutent à l'url sous la forme "?paramètre=valeur". Voici le tableau des paramètres possibles pour cette méthode :

Paramètre Description Valeurs possibles Valeur par défaut Obligatoire
page Spécifie la page de résultats à récupérer. 1 à N. Avec N le numéro de la page souhaitée. 1 Non
per_page Spécifie le nombre d'items souhaités par page. 1 à 100 6 Non
since Retourne les meilleurs items classés par score depuis le temps indiqué.
Remarque : ce paramètre ne peut pas être combiné avec les paramètres "tags" ou "q".		 -24h Pour le top des 24 dernières heures.
-7d Pour le top des 7 derniers jours.
-30d Pour le top des 30 derniers jours.
-forever Pour le top depuis toujours.
-realtime Pour les derniers items arrivés.
 24h Non
tags Filtre les items contenant le ou les tags indiqués, séparé par des "+".
Remarque : ce paramètre ne peut pas être combiné avec les paramètres "since" ou "q".		 Caractère(s). -- Non
q Filtre les items contenant le ou les mots spécifiés, séparé par des "+".
Remarque : ce paramètre ne peut pas être combiné avec les paramètres "since" ou "tags".		 Caractère(s). -- Non

Réponse type

Voici une réponse type contenant des items. Voici trouverez une explication détaillée de chacune des balises XML retournées dans la section "Annexe : Documentation des retours XML". 
<?xml version="1.0" encoding="UTF-8"?>
<items type="array">
   <item site="piicpets.com" 
    updated_at="2010-07-16 14:54:17 +0200" 
    permalink="http://piicpets.com/animaux/ohhh-isseeeuhhhhhhhh-lulu-hamster-russe-petit-1" 
    GS="G1I" 
    vote_for_count="12" 
    comments_count="4" 
    vote_against_count="0" 
    id="1" 
    created_at="2010-01-15 15:06:43 +0100" 
    score="12"> 
      <element type="image" 
        slot="teaser" 
        pos="10" 
        name="image" 
        id="1"> 
         <value big="http://waluu-eu-element-images-production.s3.amazonaws.com/images/1/-big.jpg?1263564403" 
        medium="http://waluu-eu-element-images-production.s3.amazonaws.com/images/1/-medium.jpg?1263564403" 
        small="http://waluu-eu-element-images-production.s3.amazonaws.com/images/1/-small.jpg?1263564403" 
        original="http://waluu-eu-element-images-production.s3.amazonaws.com/images/1/-original.jpg?1263564403"> 
         </value> 
      </element> 
      <element type="string" 
        slot="title" 
        pos="20" 
        name="title" 
        id="2"> 
         <value>Ohhh isseeeuhhhhhhhh</value> 
      </element> 
      <tag name="lulu" id="1" /> 
      <tag name="hamster" id="2" /> 
      <tag name="russe" id="3" />
      <tag name="petit" id="4" /> 
      <user last_name="Mar&#233;chal" 
        website="" 
        gender="m" 
        created_at="2010-01-25 11:34:32 +0200" 
        comments_count="6" 
        login="benoit" 
        followers_count="1" 
        updated_at="2010-07-15 11:13:56 +0200" 
        id="5" 
        items_count="102" 
        followings_count="7" 
        birthday="2010-03-15" 
        score="51" 
        first_name="Beno&#238;t" 
        site_id="2" 
        location="">
         <bio></bio>
         <avatar medium="http://waluu-eu-avatars-production.s3.amazonaws.com/avatars/3/benoit-medium.jpg?1264280935" 
            small="http://waluu-eu-avatars-production.s3.amazonaws.com/avatars/3/benoit-small.jpg?1264280935"
            original="http://waluu-eu-avatars-production.s3.amazonaws.com/avatars/3/benoit-original.jpg?1264280935"
            updated_at="2010-02-03 14:20:11 +0100" />
      </user>
   </item>

  ...suite tronquée...

</items>

Explications

Comme vous pouvez le constater un item est composé d'éléments correspondant aux différents champs saisis lors de la création d'un item.
Exemples :

  • Pour poeemms.com, l'item est composé d'un élément contenant le titre, et d'un élément contenant le poème.
  • Pour piicpets.com l'item est composé d'un élément contenant le tite (facultatif), d'un élément contenant l'image, d'un élément contenant la description et d'un élément contenant le nom de l'animal.
Chaque élément est typé, les différents types sont :
  • String : Chaine de moins de 255 caractères.
  • Text : Comme "String" mais sans la limitation sur le nombre de caractères.
  • Html : Comme "Text" mais certains tags HTML sont autorisés.
  • Image : Contenant les urls vers les différentes dimensions d'une image.
  • Link : Contenant un titre et une url. (Utilisé notamment sur knily.com).

Ces éléments sont affichés par position (tag <pos>) croissante et vous pouvez identifier les éléments du titre, de l'accroche et du reste grâce à l'attribut <slot> indiquant respectivement "title", "teaser" et "rest".

Exemples

http://www.piicpets.com/api/items.xml

» Retourne les items de la page d'accueil de piicpets.com 

http://www.piicpets.com/api/items.xml?tags=chat&page=2&per_page=4

» Retourne la deuxième page des items de Piicpets taggués par "chat" en considérant 4 items par page. 

http://www.knily.com/api/items.xml?q=ma+recherche

» Retourne les liens de Knily contenant "ma recherche".

Créer un item

Permet la création d'un item sur le Waluu Site spécifié.

Méthode d'appel

POST http://<hôte>/api/items.xml

<hôte> : Correspond au Waluu Site sur lequel on va créer l'item. Exemple : www.jookees.com.

Cette méthode nécessite la spécification de paramètres POST pour définir l'item à créer. Comme l'API fonctionne pour tous les Waluu Sites et que ceux-ci ont des items contenant des éléments différents, les paramètres à spécifier sont différents pour chaque Waluu Site. Afin de comprendre et savoir très facilement quels paramètres sont à spécifier pour un Waluu Site donné nous vous recommandons fortement de consulter la méthode Informations sur les champs de l'item.

Les paramètres ci-dessous sont les paramètres qu'on peut renseigner sur tous les items.

Paramètre Description Valeurs possibles Valeur par défaut Obligatoire
tags liste de tags séparés par un espace et/ou regroupé par des guillemets chaine de caractères Non

Réponse type

Si aucunes erreurs n'est survenues le code de status HTTP de retour est 201 signifiant qu'une ressource a correctement été créée. Et la réponse au format XML contient le récapitulatif de l'item avec notamment son identifiant. Exemple : 

<?xml version="1.0" encoding="UTF-8"?>
<item vote_for_count="1" 
    created_at="2010-07-15 11:13:54 +0200" 
    vote_against_count="0" 
    permalink="http://www.knily.com/lien/lien-vers-l-api-waluu-com-http-documentation-955" 
    site="liinnks.com" 
    comments_count="0" 
    updated_at="2010-07-15 11:13:56 +0200" 
    id="955" 
    GS="G1L" 
    score="1">
    <element type="link" 
        name="link" 
        pos="10" 
        slot="title" 
        id="1992">
      <value>Lien vers l'API Waluu.com</value>
      <url>http://api.waluu.com</url>
    </element>
    <element type="text" 
        name="desc" 
        pos="20" 
        slot="teaser" 
        id="1993">
      <value>Documentation de l'API de Waluu.</value>
   </element>
   
    <tag id="301" name="API" />
    <tag id="302" name="waluu" />
    <tag id="303" name="documentation" />
   
   <user last_name="Mar&#233;chal" 
        website="" 
        gender="m" 
        created_at="2010-01-25 11:34:32 +0100" 
        comments_count="6" 
        login="benoit" 
        followers_count="1" 
        updated_at="2010-07-15 11:13:56 +0200" 
        id="5" 
        items_count="102" 
        followings_count="7" 
        birthday="2010-03-15" 
        score="51" 
        first_name="Beno&#238;t" 
        site_id="2" 
        location="">
      <bio></bio>
      <avatar medium="http://waluu-eu-avatars-production.s3.amazonaws.com/avatars/3/benoit-medium.jpg?1264280935" 
            small="http://waluu-eu-avatars-production.s3.amazonaws.com/avatars/3/benoit-small.jpg?1264280935"
            original="http://waluu-eu-avatars-production.s3.amazonaws.com/avatars/3/benoit-original.jpg?1264280935"
            updated_at="2010-02-03 14:20:11 +0100" />
    </user>
</item>

Exemples

Exemple avec CURL (utilitaire en ligne de commande permettant l'envoi de requêtes HTTP) : 

curl -d "body=Ceci est une blague" http://test_login:test_password@www.jookees.com/api/items.xml

» Crée un item (une blague) sur jookees.com. 

curl -d "link_title=Blog officiel de Waluu.com" 
     -d "link_url=http://www.waluutwins.com" 
     -d "body=Voici le lien vers le blog des créateurs du portail Waluu.com" 
     -d "tags=blog waluu" 
     http://test_login:test_password@www.knily.com/api/items.xml

» Crée un item sur knily.com.

Informations sur les champs de l'item

Affiche les informations essentielles pour créer ou mettre à jour un item. Cette méthode permet notamment de savoir quels champs sont obligatoirement à renseigner lors de la création de l'item.

Méthode d'appel

GET http://<hôte>/api/items/new.xml

<hôte> : Correspond au Waluu Site sur lequel on va créer l'item. Exemple : www.jookees.com.

Réponse type

Exemple avec le retour de http://www.knily.com/api/items/new.xml: 

<?xml version="1.0" encoding="UTF-8"?>
<fields> 
  <field name="link_url" type="link_url" pos="10" slot="title" desc="Entrez le titre et l'url du lien" required="true" input_type="text_field" visible="true" /> 
  <field name="link_title" type="link_title" pos="10" slot="title" desc="Entrez le titre et l'url du lien" required="true" input_type="text_field" visible="true" /> 
  <field name="body" type="text" slot="teaser" pos="20" desc="Donnez une description a ce lien" required="false" input_type="text_area" visible="false"/> 
  <field name="tags" type="text" slot="" pos="" desc="Mots cl&#233;s" required="false" input_type="text_field" visible="true"/> 
</fields>

Détails de la réponse

Vous retrouverez dans la documentation de la balise <field> la signification de chacuns des attributs de cette balise.

Mettre à jour un item

Permet la mise à jour d'un item. :

Méthode d'appel

PUT http://<hôte>/api/items/<item_id>.xml

<hôte> : Correspond au Waluu Site sur lequel on va créer l'item. Exemple : www.jookees.com. <item_id> : Correspond à l'identifiant de l'item à mettre à jour.

Vous noterez qu'il faut utiliser la méthode HTTP "PUT". (Ou utiliser la méthode HTTP POST met en rajoutant le paramètre "_method=put".)

Comme pour la création de l'item il est nécessaire de connaitre (grâce à la méthode Informations sur les champs de l'item), le nom des champs à renseigner.

Les paramètres ci-dessous sont les paramètres qu'on peut mettre à jour sur tous les items.

Paramètre Description Valeurs possibles Valeur par défaut Obligatoire
tags liste de tags séparés par un espace et/ou regroupé par des guillemets chaine de caractères Non

Réponse type

Si aucunes erreurs n'est survenues le code de status HTTP de retour est 200.

Exemples

Exemple avec CURL (utilitaire en ligne de commande permettant l'envoi de requêtes HTTP) : 

curl -X PUT -d "body=Ceci est une nouvelle blague" http://test_login:test_password@www.jookees.com/api/items/1234.xml

» Met à jour la blague d'identifiant 1234 sur jookees.com. 

curl -d "link_title=WaluuTwins - Blog de Waluu.com" 
    http://test_login:test_password@www.knily.com/api/items/12345.xml

» Met à jour le titre du lien dont l'identifiant de l'item est 12345.

Supprimer un item

Permet la suppression d'un item.

Méthode d'appel

DELETE http://<hôte>/api/items/<item_id>.xml

<hôte> : Correspond au Waluu Site sur lequel on va supprimer l'item. Exemple : www.jookees.com. <item_id> : Correspond à l'identifiant de l'item à supprimer.

Vous noterez qu'il faut utiliser la méthode HTTP "DELETE". (Ou utiliser la méthode HTTP POST met en rajoutant le paramètre "_method=delete".)

Réponse type

Si aucunes erreurs n'est survenues le code de status HTTP de retour est 200.

Exemples

Exemple avec CURL (utilitaire en ligne de commande permettant l'envoi de requêtes HTTP) : 

curl -X DELETE http://test_login:test_password@www.jookees.com/api/items/1234.xml

» Supprime la blague d'identifiant 1234 sur jookees.com. 

curl -X DELETE http://test_login:test_password@www.knily.com/api/items/12345.xml

» Supprime l'item d'identifiant 12345.

Lister les commentaires (comments.xml)

Liste les derniers commentaires d'un item donné.

URL d'appel

GET http://<hôte>/api/comments.xml

<hôte> : Correspond au Waluu Site sur lequel on effectue la recherche. Exemple : www.jookees.com.

Paramètre Description Valeurs possibles Valeur par défaut Obligatoire
item_id Spécifie l'identifiant de l'item dont on souhaite obtenir les commentaires. Les commentaires sont affichés par ordre antichronologique. ID d'un item -- Oui

Réponse type

Voici une réponse type. Vous trouverez la documentation détaillé de la balise <comment> dans l'annexe "Documentation des retours XML". 
<?xml version="1.0" encoding="UTF-8"?>
    <comments type="array">
      <comment id="55" 
        item_id="2"     
        update_at="2010-02-08 14:37:21 +0100" 
        created_at="2010-02-08 14:37:21 +0100"> 
        <body>Trop forte !</body> 
    </comment>
</comments>

Exemples

http://www.piicpets.com/api/comments.xml?item_id=2

» Retourne les commentaires de l'item dont l'identifiant est 2.

Créer un commentaire

Permet la création d'un commentaire sur l'item spécifié.

Méthode d'appel

POST http://<hôte>/api/comments.xml

<hôte> : Correspond au Waluu Site sur lequel on va créer le commentaire. Exemple : www.jookees.com.

Les paramètres doivent être envoyés avec la méthode HTTP POST.

Voici les deux paramètres à renseigner obligatoirement pour la création d'un commentaire.

Paramètre Description Valeurs possibles Valeur par défaut Obligatoire
item_id Identifiant de l'item sur lequel on souhaite envoyer le commentaire. Nombre entier Oui
body Contenu du commentaire Chaine de caractères Oui

Réponse type

Si aucunes erreurs n'est survenues le code de status HTTP de retour est 201 signifiant qu'une ressource a correctement été créée. Et la réponse au format XML contient le récapitulatif du commentaire avec notamment son identifiant. Vous trouverez la documentation détaillé de la balise <comment> dans l'annexe "Documentation des retours XML".
Exemple : 

<?xml version="1.0" encoding="UTF-8"?>
<comment id="52" 
   item_id="961" 
   update_at="2010-07-16 11:43:04 +0200" 
   created_at="2010-07-16 11:43:04 +0200" >
   <body>Ce site est g&#233;nial</body>
   <user last_name="Mar&#233;chal" 
        website="" 
        gender="m" 
        created_at="2010-01-25 11:34:32 +0100" 
        comments_count="6" 
        login="benoit" 
        followers_count="1" 
        updated_at="2010-07-15 11:13:56 +0200" 
        id="5" 
        items_count="102" 
        followings_count="7" 
        birthday="2010-03-15" 
        score="51" 
        first_name="Beno&#238;t" 
        site_id="2" 
        location="">
      <bio></bio>
      <avatar medium="http://waluu-eu-avatars-production.s3.amazonaws.com/avatars/3/benoit-medium.jpg?1264280935" 
            small="http://waluu-eu-avatars-production.s3.amazonaws.com/avatars/3/benoit-small.jpg?1264280935"
            original="http://waluu-eu-avatars-production.s3.amazonaws.com/avatars/3/benoit-original.jpg?1264280935"
            updated_at="2010-02-03 14:20:11 +0100" />
    </user>
</comment>

Exemples

Exemple avec CURL (utilitaire en ligne de commande permettant l'envoi de requêtes HTTP) : 

curl -d "item_id=961" -d "body=Ce site est génial" http://test_login:test_password@www.knily.com/api/comments.xml

» Crée un commentaire sur l'item d'identifiant 961.

Mettre à jour un commentaire

Permet la mise à jour d'un commentaire.

Méthode d'appel

PUT http://<hôte>/api/comments/<comment_id>.xml

<hôte> : Correspond au Waluu Site sur lequel on va créer le commentaire. Exemple : www.jookees.com. <comment_id> : Correspond à l'identifiant du commentaire à mettre à jour.

Vous noterez qu'il faut utiliser la méthode HTTP "PUT". (Ou utiliser la méthode HTTP POST met en rajoutant le paramètre "_method=put".)

Les paramètres doivent être envoyés avec la méthode HTTP POST.

Voici les deux paramètres que vous pouvez modifier.

Paramètre Description Valeurs possibles Valeur par défaut Obligatoire
item_id Identifiant de l'item sur lequel on souhaite envoyer le commentaire. Nombre entier Non
body Contenu du commentaire Chaine de caractères Non

Réponse type

Si aucunes erreurs n'est survenues le code de status HTTP de retour est 200.

Exemples

Exemple avec CURL (utilitaire en ligne de commande permettant l'envoi de requêtes HTTP) : 

curl -X PUT -d "body=Mise a jour du commentaire" http://test_login:test_password@www.knily.com/api/comments/53.xml

» Met à jour le contenu du commentaire d'identifiant 53.

Supprimer un commentaire

Permet la suppression d'un commentaire.

Méthode d'appel

DELETE http://<hôte>/api/comments/<comment_id>.xml

<hôte> : Correspond au Waluu Site sur lequel on va supprimer le commentaire. Exemple : www.jookees.com.
<comment_id> : Correspond à l'identifiant du commentaire à supprimer.

Vous noterez qu'il faut utiliser la méthode HTTP "DELETE". (Ou utiliser la méthode HTTP POST met en rajoutant le paramètre "_method=delete".)

Réponse type

Si aucunes erreurs n'est survenues le code de status HTTP de retour est 200.

Exemples

Exemple avec CURL (utilitaire en ligne de commande permettant l'envoi de requêtes HTTP) : 

curl -X DELETE http://test_login:test_password@www.knily.com/api/comments/53.xml

» Supprime le commentaire d'identifiant 53 sur knily.com.

Lister les utilisateurs (users.xml)

Affiche les utilisateurs triés par score ou par date d'inscription.

URL d'appel

GET http://<hôte>/api/users.xml

<hôte> : Correspond au Waluu Site sur lequel on effectue la recherche. Exemple : www.jookees.com.

Paramètre Description Valeurs possibles Valeur par défaut Obligatoire
page Spécifie la page de résultats à récupérer. 1 à N. Avec N le numéro de la page souhaitée. 1 Non
per_page Spécifie le nombre d'utilisateurs souhaités par page. 1 à 100 10 Non
since Retourne les meilleurs utilisateurs classés par score (d'un Waluu Site donné) depuis le temps indiqué.
Remarque : Ne peut pas être combiné avec le paramètre "q". 		-24h Pour le top des 24 dernières heures.
-7d Pour le top des 7 derniers jours.
-30d Pour le top des 30 derniers jours.
-forever Pour le top depuis toujours.
-realtime Pour les derniers items créés.
 24h Non
q Filtre les utilisateurs répondant aux mots clés spécifiés, séparés par des "+".
Remarque : Ne peut pas être combiné avec le paramètre "since". 		Caractère(s). -- Non

Réponse type

Voici une réponse type. Vous trouverez la documentation détaillé de la balise <user> dans l'annexe "Documentation des retours XML". 
<?xml version="1.0" encoding="UTF-8"?>
<users type="array"> 
   <user last_name="Mar&#233;chal" 
        website="" 
        gender="m" 
        created_at="2010-01-25 11:34:32 +0200" 
        comments_count="6" 
        login="benoit" 
        followers_count="1" 
        updated_at="2010-07-15 11:13:56 +0200" 
        id="5" 
        items_count="102" 
        followings_count="7" 
        birthday="2010-03-15" 
        score="51" 
        first_name="Beno&#238;t" 
        site_id="2" 
        location="">
         <bio></bio>
         <avatar medium="http://waluu-eu-avatars-production.s3.amazonaws.com/avatars/3/benoit-medium.jpg?1264280935" 
            small="http://waluu-eu-avatars-production.s3.amazonaws.com/avatars/3/benoit-small.jpg?1264280935"
            original="http://waluu-eu-avatars-production.s3.amazonaws.com/avatars/3/benoit-original.jpg?1264280935"
            updated_at="2010-02-03 14:20:11 +0100" />
      </user>
</users>

Exemples

http://www.piicpets.com/api/users.xml?since=forever&page=2

» Affiche la seconde page des meilleurs utilisateurs depuis la création du site.

Informations sur un utilisateur précis (users/<id|login>.xml)

Affiche les informations relatives à un utilisateur donné (items, amis, abonnés, etc.).

URL d'appel

GET http://<hôte>/api/users/<id|login>.xml

<hôte> : Correspond au Waluu Site sur lequel on effectue la recherche. Exemple : www.jookees.com.
id|login : id de l'utilisateur ou login de l'utilisateur.

Paramètre Description Valeurs possibles Valeur par défaut Obligatoire
page Spécifie la page de résultats à récupérer. 1 à N. Avec N le numéro de la page souhaitée. 1 Non
per_page Spécifie le nombre d'items souhaités par page.
Remarque :Doit être combiné avec "items=true"		 1 à 100 10 Non
follow Permet de filtrer les membres en relation avec l'utilisateur demandé. -followings Affiche les membres que l'utilisateur suit.
-followers Affiche les membres qui suivent l'utilisateur.
-mutuals Affiche les membres que l'utilisateur suit et les membres qui suivent cet utilisateur.
 - Non
items Lorsque ce paramètre vaut "true" alors se sont les items de l'utilisateur (ou des membres si le paramètre follow est renseigné) qui sont affichés. Ces items sont triés par ordre antichronologique. true -- Oui pour les paramètres "tags" et "q" uniquement
q Filtre les items de l'utilisateur répondant aux mots clés spécifiés, séparés par des "+".
Remarque : Doit être combiné avec le paramètre "items" et ne peut pas être combiné avec les paramètres "tags" ou "follow". 		Caractère(s). -- Non
tags Filtre les items de l'utilisateur contenant le ou les tags indiqués, séparés par des "+".
Remarque : Doit être combiné avec le paramètre "items" et ne peut pas être combiné avec les paramètres "q" ou "follow". 		Caractère(s). -- Non

Exemples

http://www.piicpets.com/api/users/3.xml

» Affiche les informations concernant l'utilisateur dont l'id est 3. 

http://www.piicpets.com/api/users/benoit.xml

» Affiche les informations concernant l'utilisateur dont le login est "benoit". 

http://www.piicpets.com/api/users/benoit.xml?follow=followers

» Affiche les membres qui suivent "benoit". 

http://www.piicpets.com/api/users/benoit.xml?follow=followings&items=true&page=2

» Affiche la seconde page des items des membres que "benoit" suit. Par exemple, si "benoit" suit uniquement "anthony" alors ce sont les items de ce dernier qui sont affichés. 

http://www.knily.com/api/users/benoit.xml?q=google&items=true

» Affiche les liens de "benoit" contenant "google".

Vérifier les crédentials (login et mot de passe) d'un utilisateur

Cette méthode permet de vérifier la validité du duo login et mot de passe fournit par un utilisateur.

URL d'appel

POST http://www.waluu.com/api/users/check_credentials
Voici les paramètres à fournir pour vérifier le login et le mot de passe de l'utilisateur.
Paramètre Description Valeurs possibles Valeur par défaut Obligatoire
login Pseudo de l'utilisatisateur à vérifier Chaîne de caractères Oui
password Mot de passe de l'utilisateur à vérifier Chaîne de caractères Oui

Réponse type

Si le code de retour HTTP est 200 alors les crédentials sont valide.
Si le code de retour HTTP est 401 (UnAuthenrized) alors ces dernières ne sont pas valide.

Exemples avec CURL (utilitaire permettant l'envoi de requêtes HTTP)

curl -v -d "login=test_login" -d "password=test_password" http://www.waluu.com/api/users/check_credentials

» Vérifie que le mot de passe de l'utilisateur test_login est bien test_password.

Créer un utilisateur (Inscription d'un nouveau membre)

Permet l'inscription d'un nouvel utilisateur sur la platforme Waluu. Ce qui permettra à l'utilisateur de se connecter sur n'importe quel site du réseau Waluu par la suite.

Méthode d'appel

POST http://<hôte>/api/users.xml

<hôte> : Ici l'hôte n'a pas d'importance du moment qu'il s'agit d'un site du réseau Waluu. Car l'inscription sera effective pour tous les sites. Exemple : www.waluu.com

Les paramètres doivent être envoyés avec la méthode HTTP POST.

Voici les paramètres à renseigner obligatoirement pour la création d'un utilisateur.

Paramètre Description Valeurs possibles Valeur par défaut Obligatoire
login Pseudo souhaité de l'utilisateur. 3 caractères minimum, et seul les chiffres et les lettres sont autorisés Chaîne de caractère Oui
password Mot de passe souhaité de l'utilisateur. 3 caractères minimum Chaine de caractères Oui
email EMail valide de l'utilisateur. EMail Oui

Réponse type

Si aucunes erreurs n'est survenues le code de status HTTP de retour est 201 signifiant qu'une ressource à correctement été créée. Et la réponse au format XML contient le récapitulatif du commentaire avec notamment son identifiant. Vous trouverez la documentation détaillée de la balise <user> dans l'annexe "Documentation des retours XML".

Exemples

Exemple avec CURL (utilitaire en ligne de commande permettant l'envoi de requêtes HTTP) : 

curl -d "login=testlogin" -d "password=testpassword" -d "email=valideemail@gmail.com" http://www.waluu.com/api/users.xml

» Crée un utilisateur avec le pseudo testlogin, le mot de passe testpassword et l'email valideemail@gmail.com.

S'abonner à un utilisateur (Suivre un membre)

Permet de s'abonner aux contributions d'un utilisateur.

Méthode d'appel

POST http://<hôte>/api/users.xml

<hôte> : Ici l'hôte n'a pas d'importance du moment qu'il s'agit d'un site du réseau Waluu. Car l'abonnement à un membre est effectif sur tous les sites du portail waluu. Exemple : www.waluu.com

Les paramètres doivent être envoyés avec la méthode HTTP POST.

Il faut obligatoirement est authentifié pour réaliser cette action.

Voici les paramètres à renseigner obligatoirement pour la création d'un utilisateur.

Paramètre Description Valeurs possibles Valeur par défaut Obligatoire
followed_user_id Identifiant de l'utilisateur dont on souhaite s'abonner. Nombre entier Oui

Réponse type

Si aucunes erreurs n'est survenues le code de status HTTP de retour est 201 signifiant qu'une ressource à correctement été créée.

Exemples

Exemple avec CURL (utilitaire en ligne de commande permettant l'envoi de requêtes HTTP) : 

curl -d "followed_user_id=5" http://test_login:test_password@www.waluu.com/api/follows.xml

» Abonne l'utilisateur authentifié "test_login" à l'utilisateur d'identifiant 5.

Se désabonner d'un utilisateur

Permet de ne plus suivre un membre.

Méthode d'appel

DELETE http://<hôte>/api/follows/<user_id>.xml

<hôte> : Ici l'hôte n'a pas d'importance du moment qu'il s'agit d'un site du réseau Waluu. Car l'abonnement à un membre est effectif sur tous les sites du portail waluu. Exemple : www.waluu.com
<user_id> : Correspond à l'identifiant du membre à ne plus suivre.

Vous noterez qu'il faut utiliser la méthode HTTP "DELETE". (Ou utiliser la méthode HTTP POST met en rajoutant le paramètre "_method=delete".)

Il faut obligatoirement est authentifié pour réaliser cette action.

Réponse type

Si aucunes erreurs n'est survenues le code de status HTTP de retour est 200. Sinon le code de retour 422 est renvoyé et un xml contenant le détail des erreurs est affiché.

Exemples

Exemple avec CURL (utilitaire en ligne de commande permettant l'envoi de requêtes HTTP) : 

curl -X DELETE http://test_login:test_password@www.waluu.com/api/follows/5.xml

» Supprime l'abonnement de test_login à l'utilisateur d'identifiant 5

Créer un vote

Permet la création d'un vote sur l'item ou le commentaire spécifié.

Méthode d'appel

POST http://<hôte>/api/votes.xml

<hôte> : Correspond au Waluu Site sur lequel on va créer le vote. Exemple : www.jookees.com.

Les paramètres doivent être envoyés avec la méthode HTTP POST.

Voici les paramètres a renseigner pour la création d'un vote.

Paramètre Description Valeurs possibles Valeur par défaut Obligatoire
item_id Identifiant de l'item sur lequel on souhaite voter. Nombre entier Oui (sauf si comment_id est déjà spécifié)
comment_id Identifiant du commentaire sur lequel on souhaite voter. Nombre entier Oui (sauf si item_id est déjà spécifié)
vote Valeur du vote : 1 pour voter plus, -1 pour voter moins Nombre entier relatif Oui

Réponse type

Si aucunes erreurs n'est survenues le code de status HTTP de retour est 201 signifiant qu'une ressource a correctement été créée. Et la réponse au format XML contient le récapitulatif du commentaire avec notamment son identifiant. Exemple : 

<?xml version="1.0" encoding="UTF-8"?>
<vote created_at="2010-07-16 13:38:46 +0200" comment_id="" vote="1" id="277" item_id="950"/>

Exemples

Exemple avec CURL (utilitaire en ligne de commande permettant l'envoi de requêtes HTTP) : 

curl -d "item_id=950" -d "vote=1" http://test_login:test_password@www.knily.com/api/votes.xml

» Voter positivement sur l'item d'identifiant 950. 

curl -d "comment_id=54" -d "vote=-1" http://test_login:test_password@www.knily.com/api/votes.xml

» Voter négativement sur le commentaire d'identifiant 54.

Annexe : Documentation des retours XML

Balise item

Détails des attributs et sous balises de la balise <item>.

Type (attribut/balise) Nom Description Format Exemple
Attribut id Identifiant de l'item (unique sur tous le portail Waluu.com) Nombre entier 1
Attribut site Site d'appartenance de l'item (utile lorsqu'on requête sur Waluu.com) Chaîne de caractères jookees.com
Attribut created_at Date de création Date (format YYYY-MM-DD HH:MM:SS GMT) 2010-07-16 14:54:17 +0200
Attribut updated_at Date de mise à jour Date (format YYYY-MM-DD HH:MM:SS GMT) 2010-07-16 14:54:17 +0200
Attribut permalink Lien vers l'item Chaîne de caractères http://piicpets.com/animaux/ohhh-isseeeuhhhhhhhh-lulu-hamster-russe-petit-1
Attribut score Soustraction entre le nombre de votes positifs et le nombre de votes négatifs Nombre entier 12
Attribut vote_for_count Nombre de votes positifs Nombre entier 20
Attribut vote_against_count Nombre de votes négatifs Nombre entier 20
Attribut comments_count Nombre de commentaires sur l'item Nombre entier 5
Attribut GS Type de site d'appartenance de l'item (G1I site d'images, G1L site de liens, G1T site de texte) Chaîne de caractères G1I
Balise element Elément de l'item. Voir la documentation sur la balise element Multiple balises <element>possible
Balise tag Mot clé de l'item. Voir la documentation sur la balise tag Multiple balises <tag> possible
Balise user Utilisateur qui a créé l'item. Voir la documentation sur la balise user Une seule balise <user> possible

Balise tag

Détails des attributs et sous balises de la balise <tag>.

Type (attribut/balise) Nom Description Format Exemple
Attribut id Identifiant du mot clé (unique sur tous le portail Waluu.com) Nombre entier 1
Attribut name Nom du mot clé Chaîne de caractères hamster

Balise element

Détails des attributs et sous balises de la balise <element>.

Type (attribut/balise) Nom Description Format Exemple
Attribut id Identifiant de l'élément (unique sur tous le portail Waluu.com) Nombre entier 1
Attribut name Nom de l'élément Chaîne de caractères title
Attribut slot Slot de l'élément. Permet de savoir si l'élément appartien au titre ("title") a l'accroche ("teaser") ou au reste ("rest") de l'item Chaîne de caractères title
Attribut pos Position de l'élément Nombre entier 10
Balise value Valeur de l'élément. Voir la documentation de la balise <value> Une seule balise <value> possible

Balise value

Détails des attributs et sous balises de la balise <value>.

Type (attribut/balise/text) Nom Description Format Exemple
Text Le texte de cette balise contient la valeur de l'élément Chaîne de caractères Ceci est un texte.
Attribut original(si l'élément est une image) URL vers l'image de taille original URL http://waluu-eu-element-images-production.s3.amazonaws.com/images/1597/bronzette-de-monsieur-doigt-plage-bronze-original.jpg
Attribut big(si l'élément est une image) URL vers l'image de taille big (400x325>) URL http://waluu-eu-element-images-production.s3.amazonaws.com/images/1597/bronzette-de-monsieur-doigt-plage-bronze-big.jpg
Attribut medium(si l'élément est une image) URL vers l'image de taille medium (325x265>) URL http://waluu-eu-element-images-production.s3.amazonaws.com/images/1597/bronzette-de-monsieur-doigt-plage-bronze-medium.jpg
Attribut small(si l'élément est une image) URL vers l'image de taille small (160x130>) URL http://waluu-eu-element-images-production.s3.amazonaws.com/images/1597/bronzette-de-monsieur-doigt-plage-bronze-small.jpg
Attribut url(si l'élément est un lien) URL du lien URL http://www.google.com

Balise user

Détails des attributs et sous balises de la balise <user>.

Type (attribut/balise/text) Nom Description Format Exemple
Attribut id Identifiant de l'utilisateur (unique sur tout le portail Waluu.com) Nombre entier 1
Attribut login Pseudo unique de l'utilisateur Chaîne de caractères benoit
Attribut first_name Prénom de l'utilisateur Chaîne de caractères Benoit
Attribut last_name Nom de famille de l'utilisateur Chaîne de caractères Maréchal
Attribut gender Sexe de l'utilisateur ("m" pour masculin et "f" pour féminin) Caractère m
Attribut birthday Date de naissance de l'utilisateur Date 1984-07-13
Attribut created_at Date d'inscription de l'utilisateur Date 2010-01-17 11:36:55 +0100
Attribut updated_at Date de dernière activité de l'utilisateur Date 2010-07-16 14:53:48 +0200
Attribut location Lieux d'habitation Chaîne de caractères Lyon, France
Attribut website URL du site personnel URL http://www.benoitmarechal.com
Attribut score Somme des scores des items de l'utilisateur sur le waluu site spécifié Nombre entier 42
Attribut items_count Nombre d'items sur le waluu site spécifié Nombre entier 169
Attribut comments_count Nombre de commentaires de l'utilisateur sur le waluu site spécifié Nombre entier 14
Attribut followings_count Nombre de membres que l'utilisateur suit Nombre entier 10
Attribut followers_count Nombre de membres qui suivent l'utilisateur Nombre entier 25
Balise avatar Image représentant l'utilisateur. Voir la documentation de la balise <avatar> Balise
Balise bio Texte de présentation de l'utilisateur Texte

Balise avatar

Détails des attributs et sous balises de la balise <avatar>.

Type (attribut/balise/text) Nom Description Format Exemple
Attribut updated_at Date de mise à jour de l'avatar. Permet de savoir si l'utilisateur a changé sa photo de profil. Date 2010-01-23 22:08:55 +0100
Attribut original URL vers l'image de taille original de l'avatar URL http://waluu-eu-avatars-production.s3.amazonaws.com/avatars/3/benoit-original.jpg
Attribut medium URL vers l'image de taille medium de l'avatar URL http://waluu-eu-avatars-production.s3.amazonaws.com/avatars/3/benoit-medium.jpg
Attribut small URL vers l'image de taille small de l'avatar URL http://waluu-eu-avatars-production.s3.amazonaws.com/avatars/3/benoit-medium.jpg

Balise comment

Détails des attributs et sous balises de la balise <comment>.

Type (attribut/balise/text) Nom Description Format Exemple
Attribut id Identifiant du commentaire (unique sur tout le portail Waluu.com). Nombre entier 1
Attribut created_at Date de création du commentaire Date 2010-06-30 21:42:42 +0200
Attribut updated_at Date de mise à jour du commentaire Date 2010-06-30 21:42:42 +0200
Balise body Balise dont le texte contient le corp du commentaire Text Exemple de commentaire

Balise field

Détails des attributs et sous balises de la balise <field>.

Type (attribut/balise/text) Nom Description Format Exemple
Attribut name Nom du champ Chaîne de caractères link_url
Attribut desc Description du champ Chaîne de caractères Url du lien a renseigner
Attribut slot Emplacement du champ dans l'item. title si le champ est dans le titre, teaser s'il est dans l'entête et rest s'il est dans le rest de l'item. Chaîne de caractères teaser
Attribut input_type Champ de saisi conseillé.
  • "text_field", pour un champ de saisi sur une ligne (input type text en html).
  • "text_area", pour un champ de saisi multi-ligne (text area en html)
  • "file_field", pour saisir un fichier (input type file en html)
  • "date_field", pour saisir une date.
  • "date_field_mmyy", pour saisir une date avec le mois et l'année seulement.
Chaîne de caractères text_field
Attribut type Type de champ Chaîne de caractères link_url
Attribut pos Position du champ dans l'item parmis les autres champs Nombre entier 10
Attribut required Permet de savoir si le champ est obligatoirement à saisir "true" si le champ est requis, "false" sinon true
Attribut visible Permet de savoir si le champs est affiché par défaut "true" si le champ est affiché, "false" sinon true

Balise site

Détails des attributs et sous balises de la balise <site>.

Type (attribut/balise/text) Nom Description Format Exemple
Attribut id Identifiant du site Nombre entier 1
Attribut domain Nom de domain du site Chaîne de caractères knily.com
Attribut item_name Nom de l'item au singulier. Chaîne de caractères blague
Attribut items_name Nom de l'item au pluriel. Chaîne de caractères blagues
Attribut items_name Nom de l'item au pluriel. Chaîne de caractères blagues
Attribut item_seo Nom de l'item au singulier utilisé pour le référencement. Chaîne de caractères blague
Attribut items_seo Nom de l'item au singulier utilisé pour le référencement. Chaîne de caractères blagues
Attribut vote_for Nom du vote positif. Chaîne de caractères J'adore
Attribut welcome_message Message de bienvenu du site Chaîne de caractères Bienvenu sur Jookees.com
Attribut itemer Nom des membres du site Chaîne de caractères Blagueurs (pour Jookees.com)
Attribut created_at Date de création du site Date 2010-01-30 13:01:23 +0100
Attribut updated_at Date de mise à jour du site. Utile pour mettre en cache les informations du site et les faire expirer lorsque le site à été mis à jour. Date 2010-01-30 13:01:24 +0100

Contact

N'hésitez pas à nous contacter directement sur twitter @waluutwins, ou par email : contact@waluutwins.com pour la moindre question :).


Dernière modification : 22/07/2010