Une FAQ sur l'API des Nabz

Bon, comme je suis trop gentil et que j'en ai un peu ras-le-bol de voir toujours les mêmes questions (et pis pour ceux qui les posent c'est pas sympa d'avoir à attendre une réponse), voici une jolie FAQ sur l'API des Nabz ! Elle sera obsolète avec l'arrivée des Karotz (virtualisation, SDK Javascript, toussa), mais bon c'est déjà ça d'avoir une FAQ sous la main.

Q : C'est quoi l'API ?
R : Je vais prendre la jolie réponse de _melka (attention c'est lui) :

_melka a écrit:

L'api sert à communiquer directement avec le lapin. En gros lui envoyer des lignes de commande via un navigateur web pour le faire parler, bouger ses oreilles, faire des chorégraphie, lire des mp3 ou des radios web et plus généralement créer des applications pour le Nabaztag en utilisant son numéro de série et son numéro de token. J'espère que cette réponse est claire et pas trop technique.

Attention, l'API n'est pas limité à un navigateur web. Si vous connaissez un langage de programmation, vous pouvez faire plein de trucs sympas avec !

Q : Ho mais c'est taupe coule ! Oussékonapprend ?
R : Le Fucking Manual est là.

Q : Mais j'aime pas Shakespeare moi !
R : Pas de problème, votre serviteur a tout traduit en français ici.

Q : C'est génial ton truc ! Je m'en sert comment avec PHP ?
R : Comme ça :

Code:

<?php
$request = file_get_contents('http://api.nabaztag.com/blabla');
if(!$request) exit('La requête a foiré !');
?>

Attention, ça marche pas si la directive de config' allow_url_fopen est sur Off, voyez avec votre hébergeur (faites gaffe aussi chez Free, c'est à On mais ça marche pas quand même). Y'a aussi une méthode alternative avec curl, mais je sais plus où ça a été posté, si vous vous sentez une âme d'Indiana Jones-archéologue-dépoussiéreur-de-topics, libre à vous d'aller chercher (mais bonne chance quand même ).

Q : C'est compatible avec quels langages cette API ?
R : Avec n'importe quoi, pourvu que ça puisse ouvrir une connexion HTTP (ou si t'aimes le bas-niveau / t'es maso / t'as pas le choix / c'est plus simple, avec des sockets). On peut aussi utiliser l'XHR Cross-Domain avec Javascript, mais ça ne marche qu'avec des navigateurs récents.

Q : Pfff c'est nul, ça fonctionne jamais !
R : Tapez pas tapez pas, l'API est souvent en rade, à cause des problèmes de serveurs. Si vous êtes en train de vous en servir c'est rageant, mais vous êtes obligés de prendre votre mal en patience.

Q : Comment je fais pour faire marcher la radio ?
R : Tout est là.

Q : C'est moche le Call URL en PHP ! T'as pas mieux ?
R : Si, là (avec XML) et là (en full-POO, c'est-y pas beau ?).

Q : Je veux me servir de Java, et j'aime pas HTTP GET. T'as pas quelque chose ?
R : Si, là. C'est une API LGPL, bien documentée et qui comporte (à peu près) toutes les fonctionnalités de l'API, sauf le streaming (à l'heure où j'écris ces lignes).

Q : J'y comprend vraiment, mais alors vraiment rien. Qu'est-ce que je peux faire ?
R : Il existe de nombreux sites d'applications pour faire ses chorégraphies et plein d'autres trucs sympas (en vrac nabzone, nabzap, Chez Patapwet...). Phabbrrysse a également fait un script qui permet de faire facilement ses chorégraphies avec Excel.

Q : Est-ce qu'avec l'API je peux utiliser le micro du Nabaztag, ou savoir quand le bouton a été appuyé ?
R : Non, l'API permet juste d'agir sur le Nabaztag, pas de récupérer les évènements matériels du lapin. Mais elle permet quand même de récupérer la position des oreilles, de savoir si le lapin dort, quels amis il a etc.

Q : Que se passe-t-il si je fais plusieurs appels simultanés à l'API ?
R : Ne vous inquiétez pas, il y a un mécanisme de queue : vos requêtes seront exécutées à la suite. C'est aussi valable pour les autres applis : par exemple, si votre Nabz lit une radio, les Taï-Chi seront joués après que vous ayez stoppé la lecture, qui ne sera pas coupée. Néanmoins, comme le conseille Diaoul, il vaut mieux mettre un petit « sleep » (autrement dit une pause dans votre programme) pour faciliter la compréhension des messages par l'API (sinon, certains messages partiront à la trappe lors de la lecture mais seront visibles sur my.violet.net).

Q : Je peux envoyer des messages aussi long que je veux via l'API ?
R : Non, a priori il y a une limite dans les 300 à 500 caractères (selon les sources) pour les TTS.

Q : Mais alors, à ce moment là, si je passais en méthode POST, et pas en GET ?
R : Ouais, mais en fait non, ça ne marche pas mieux. Bien tenté cela dit.

Q : Comment je fais si je veux coder mon propre proxy ? Y'a de la doc quelque part ?
R : Oui, là. Attention c'est en anglais (mais c'est tout ce qu'il y a de plus complet).

Q : Est-ce que c'est la peine de continuer à coder, étant donné que la nouvelle API arrive ? Comment fait-on pour adapter ses scripts ?
R : La nouvelle API remplacera l'ancienne, mais on a très peu d'infos à son sujet. On ne peut pas anticiper le changement, les specs ne sont pas sorties. En plus, selon Mindscape, l'adaptation sera difficile. Donc, à votre place, j'arrêterais de coder et j'attendrais la nouvelle API (à moins que vous n'ayez du temps à perdre).

---

J'éditerai au fur et à mesure que je vois des questions qui reviennent souvent / que vous en postez juste en dessous / que vous m'en envoyez. Si vous avez une info capitale (ou même mineure) / vu une bourde, faites-en moi part !

---

Hall of Fame
Merci à :

• sinmaniphel
  
• Hunta_de_la_Radieuse
  
• Phabbrrysse
  
• Diaoul
  
• tiboztag
  

Bonne initiative :o

Q : est-ce qu'avec l'API je peux utiliser le micro du Nabaztag ou savoir quand le bouton a été appuyé

R : non, l'API permet juste d'agir sur le nabaztag, pas de récupérer les évènements matériels du lapin

@sinmaniphel : nickel merci, j'édite !

sinmaniphel a écrit:

R : non, l'API permet juste d'agir sur le nabaztag, pas de récupérer les évènements matériels du lapin

Oui et non : pas des événements certes, mais tout de même des états et d'autres info (position des oreilles, dodo ou pas, amis, etc.)

@Hunta_de_la_Radieuse : OK merci, c'est complété !

Tiens, voila une question à laquelle je n'ai pas la réponse :
Que se passe-t-il si je fais deux appels quasi simultanés à l'API ? Y a-t-il un mécanisme de queue ? (il faudra que je teste, mais si quelqu'un a la réponse, ca m'aiderait)

Oui, pas d'inquiétude, il y a un mécanisme de queue.

Gutt, merci Harfang, ca va me simplifier la vie (j'étais déjà en train de réfléchir a schéduler des crons en décalé etc...)

Faut vraiment que je m'en offre un, de lapin, parce que je crains que ma douce en aie vite marre que je torture son pauvre Doudou.

Q : Je peux envoyer des messages aussi long que je veux via l'API ?
R : Non, a priori il y a une limite dans les 300 caractères pour les TTS

Q : Mais alors, à ce moment là, si je passais en méthode POST , et pas en GET ?
R : Ouais, mais en fait non, ça ne marche pas mieux. Bien tenté cela dit

plutot 500 la limite a priori

erf, il y a sans doute eu des evols alors. Je me réfère a un vieux post de 2006 pour ces chiffres. Mais bon, 300 ou 500, quand tu veux faire des vrais services, c'est la même chose (a peu de choses près).

Va vraiment falloir qu'ils soignent le SDK sur les karotz, parce leur doc est quand même un poil frustrante (genre il y a des messages d'erreur sur les "abus" d'API, mais on ne connait pas les conditions de déclenchement, le système de queue n'est pas expliqué, etc)

Au sujet de la queue. Pour effectuer l'envoi de plusieurs messages d'affilés au même lapin je conseil de mettre un petit "sleep" pour faciliter la compréhension par l'API de l'ordre des messages.
Par ailleurs, il arrive parfois que la queue marche mal donc en mettant un sleep de 5 secondes, le lapin lit le message en 7 secondes, il reste 2 secondes de battement et la queue se débrouille bien. Sans quoi, il y a un ou plusieurs messages qui passent à la trappe à la lecture par le lapin (mais visible sur my.violet)

Voiloù

J'ai corrigé une faute de typo, j'ai modifier le paragraphe sur Javascript et j'ai ajouté une Q/R sur la nouvelle API.

ET faudra refaire le boulot quand la nouvelle API va sortir...
Merci !

C'est pas grave, y'en a qui s'en servent encore.