Zopieux's adventures

Le développement des applications mobile du le Site du Zéro (disponible depuis le 21 novembre 2011 pour la version Android) a été l’occasion pour les développeurs de Simple IT de commencer une ébauche d’API afin d’assurer la livraison du contenu aux applications en question. En effet, même si à ce jour ces dernières ne sont que des webviews reliées par quelques menus, il n’était pas envisageable de récupérer directement les pages du Site du Zéro pour les afficher sur le mobile : elles ne sont pas adaptées parce que trop lourdes et bourrées d’éléments qui n’ont pas leur place sur une app : menus, header, etc.

Hélas, cette API n’est pas accessible publiquement. Simple IT a prévu de l’ouvrir aux développeurs à moyen terme. En attendant une documentation officielle, cet article explique le fonctionnement de l’API utilisée pour les applications mobiles. Je l’ai réalisé en analysant le code de l’app Android disponible sur le Store. Si vous en venez à utiliser cette documentation, soyez conscients que

• ces spécifications sont susceptibles d’évoluer à tout moment et notamment lors de la mise à jour des applications développées par Simple IT. J’essaierai au mieux de maintenir à jour cet article mais mon emploi du temps chargé n’aidera pas ;
• il m’est impossible de vous dire si vous avez le droit d’utiliser cette API autrement que par l’utilisation des applications officielles : Simple IT n’a — à ma connaissance — pas publié de conditions d’utilisation.

N’hésitez pas à me faire part (en commentaire, par e-mail ou autre) de vos commentaires, notamment si vous repérez des erreurs.

 Vue d’ensemble

L’API utilise le bien connu protocole HTTP et plus précisément sa variante chiffrée, HTTPS (l’utilisation d’HTTP provoquera une erreur 403 Forbidden). Pour le moment, seules des actions de lecture sont disponibles. Il n’y a pas d’interaction faisant intervenir le compte des membres du site.

Toutes les requêtes (modulo les fichiers statiques comme les feuilles de style ou les images) sont réalisées sur api.siteduzero.com et demandent une identification par le biais d’un paramètre GET token. Sans ce token, il vous sera demandé une identification HTTP, donc l’API ne sera pas accessible.

L’API n’est pas restreinte à un User-agent particulier. Elle est servie par un serveur Apache.

On ne sait pas si l’API est limitée en nombre de requêtes par unité de temps. Une utilisation mesurée, en « bon père de famille », est donc conseillée.

Format de la réponse

Toutes les réponses sont au format JSON, dans le jeu de caractère UTF-8 (comme sur le Site du Zéro). Toute requête qui s’est bien déroulée renverra un dictionnaire de deux éléments :

• status : doit être égal à « ok » ;
• results : contient le corps de la réponse en temps que telle ; c’est ce contenu que j’appellerai « réponse type » dans la suite.

En cas d’erreur (méthode qui n’existe pas, requête sur un élément inconnu, etc.), la réponse est étrange : vous ne recevez pas un dictionnaire JSON avec autre chose que « ok » comme status mais plutôt une demande d’authentification HTTP, donc finalement une erreur 401 Unauthorized. Vous êtes prévenu !

Détail des méthodes disponibles

Références

Les réponses contiennent parfois des structures réutilisées un peu partout. Cette section liste ces structures communes auxquelles vous devez vous référer quand il est indiqué /* réf. machin */.

Catégorie

{
  "id": 42,
  "title": "Nom de la catégorie"
}

Liste d’auteurs

[
  {
    "id": 42,
    "username": "Bidule"
  }
  , ...
]

Liste de tutoriels

[
  {
    "type": <"big" ou "mini">,
    "id": 42,
    "title": "Titre du tutoriel"
  }
  , ...
]

Difficulté d’un tutoriel

1 pour facile, 2 pour modéré et 3 pour difficile.

<"1" ou "2" ou "3">

Navigation dans un chapitre

Quand vous obtenez un mini-tutoriel qui n’est pas un chapitre d’un big-tutoriel, cet objet est :

{"big": "", "next": "", "previous": ""}

En revanche, quand le mini-tutoriel fait partie d’un big-tutoriel, cet objet devient :

{
  "big":
    {
      "id": "40", /* notez le string */
      "title": "Titre du big-tuto auquel appartient ce chapitre"
    },
  "previous":
    {
      "id": "41", /* notez le string */
      "title": "Titre du chapitre (mini-tuto) précédent"
    },
  "next":
    {
      "id": "43", /* notez le string */
      "title": "Titre du chapitre (mini-tuto) suivant"
    }
}

Les éléments previous et/ou next peuvent être égaux à "" (chaîne vide) si le chapitre en cours est respectivement le premier et/ou le dernier chapitre de la partie.

Sommaine d’un mini-tutoriel

[
  "<a href=\"#ss_part_1\" >Titre du paragraphe 1</a>",
  "<a href=\"#ss_part_2\" >Titre du paragraphe 2</a>"
  , ...
]

Sommaine d’un big-tutoriel

[
  {
    "title": "Titre de la partie (ensemble de chapitres) 1",
    "mini":
      [
        {
          "icon": '',
          "id": 42,
          "index": /* réf. sommaire d'un mini-tutoriel */,
          "title": "Titre du chapitre (mini-tuto) 1"
        }
        , ... /* chapitres suivants */
      ]
  }
  , ... /* parties suivantes */
]

Contenu HTML

Les contenus textuels (donc au format HTML) sont formatés de la manière suivante (mais sans espaces) :

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <link
      rel="stylesheet"
      href="http://www.siteduzero.com/css/appli_mobile.css">
    <title>Titre</title> <!-- présent selon les cas -->
  </head>
  <body>
    <!-- contenu réel, souvent dans un div -->
  </body>
</html>

Dates/heures

Les dates sont au format AAAA-MM-JJ HH:MM:SS ou plus clairement année-mois-jour heure:minute:seconde.

Méthodes

Maintenant, voici les méthodes à proprement parler.

Hiérarchie des catégories de tutoriels

/category/tutorial
/category/tutorial/<id>

Récupère la liste des descendants hiérarchiques (fils) d’une catégorie <id> de tutoriels dans l’arbre de catégories. Si /<id> n’est pas précisé, il s’agira uniquement de la catégorie racine ie. les tutoriels (id 352), comme sur l’accueil des cours.

Remarquez que les articles, eux, ne sont pas accessibles : même si vous tentez d’en récupérer la liste en appelant /category/tutorial/353, la réponse ne contiendra pas d’élément category ! En revanche, si vous connaissez l’id d’un tutoriel se trouvant dans la catégorie Articles, rien ne vous empêche de le demander avec /mini-tutorial ou /big-tutorial.

Réponse type :

[
  {
    "title": "Nom de la catégorie",
    "id": 42,
    "icon": "http://uploads.siteduzero.com/cat/thb/1_1000/352.png",
    "total_element": 1337,
    "category": /* une liste de dictionnaires qui suivent la même structure
                   que celui-ci, sans l'élément "category" ou "tutorial"
                   bien-sûr (il n'y a qu'un seul niveau de récursion) */
  }
  , ...
]

Si la catégorie est une feuille de la hiérarchie (elle ne contient pas d’autres catégories), c’est alors une liste des tutoriels pour cette catégorie qui est retournée, dans l’élément tutorial.

Réponse type :

[
  {
    "tutorial": /* réf. liste de tutoriels */,
    "icon": "http://uploads.siteduzero.com/cat/thb/1_1000/102.png",
    "id": 42,
    "total_element": 1337,
    "title": "Titre de la catégorie (feuille)"
  }
  , ...
]

Liste des news (raccourcies)

/news?offset=<offset>&range=<range>

Récupère la liste des range dernières news (sans leur contenu, uniquement le résumé s’il existe) à partir de la offset^ième plus récente. Dans l’application officielle, range = 8.

Réponse type :

[
  {
    "title": "Titre de la news",
    "id": 42,
    "icon": "http://uploads.siteduzero.com/nws/thb/43001_44000/43306.png",
    "published_at": /* réf dates/heures */,
    "summary": "Résume de la news"
  }
  , ...
]

Contenu d’une news

/news/<id>

Récupère le contenu et les détails de la news <id>.

Attention à l’absurdité : le dictionnaire (unique, évidemment) est imbriqué dans une liste à un élément.

Réponse type :

[{
  "author": /* réf. liste d'auteurs */,
  "category": /* réf. catégorie */,
  "icon": "http://uploads.siteduzero.com/nws/thb/43001_44000/43306.png",
  "id": 42,
  "published_at": /* réf dates/heures */,
  "summary": "Résume de la news",
  "title": "Titre de la news",
  "content": "Contenu de la news" /* HTML sans conteneur */
}]

Récupération d’un mini-tuto

/mini-tutorial/<id>

Récupère la structure et les détails du mini-tutoriel <id>.

Le type (big ou mini) d’un tutoriel est précisé dans toute structure du type liste de tutoriels.
Notez que l’on ne peut savoir ni la date de création, ni la date de dernière modification des tutoriels.
Attention à l’absurdité : le dictionnaire (unique, évidemment) est imbriqué dans une liste à un élément.

Réponse type :

[{
  "author": /* réf. liste d'auteurs */,
  "conclusion": "Conclusion du tutoriel" /* réf. contenu HTML, sans <title> */,
  "introduction": "Introduction du tutoriel" /* réf. contenu HTML, sans <title> */,
  "estimated_time": "120", /* en minutes, 0 si pas précisé ; notez le string */
  "icon": "http://uploads.siteduzero.com/icones/257001_258000/257707.png",
  "id": 42,
  "level": /* réf. difficulté d'un tutoriel */,
  "mcq": "100", /* id du QCM associé ; notez le string */
  "navigation": /* réf. navigation dans un big-tutoriel */,
  "title": "Titre du mini-tutoriel",
  "type": "mini",
  "index": /* réf. sommaire d'un mini-tutoriel */,
  "content": "Contenu du mini-tutoriel" /* réf. contenu HTML, avec <title> */
}]

Récupération d’un big-tuto

/big-tutorial/<id>

Récupère la structure et les détails du big-tutoriel <id>.

Attention à l’absurdité : le dictionnaire (unique, évidemment) est imbriqué dans une liste à un élément.

Réponse type :

[{
  "author": /* réf. liste d'auteurs */,
  "conclusion": "Conclusion du tutoriel" /* réf. contenu HTML, sans <title> */,
  "introduction": "Introduction du tutoriel" /* réf. contenu HTML, sans <title> */,
  "estimated_time": "120", /* en minutes, 0 si pas précisé ; notez le string */
  "icon": "http://uploads.siteduzero.com/icones/257001_258000/257707.png",
  "id": 42,
  "level": /* réf. difficulté d'un tutoriel */,
  "title": "Titre du big-tutoriel",
  "type": "big",
  "index": /* réf. sommaire d'un big-tutoriel */,
}]

Récupération d’un QCM

/tutorial/mcq/<id>
Récupère le QCM <id>.

Les QCM ne sont pas directement dans la réponse d’un mini-tutoriel. Il faut faire une deuxième requête en utilisant l’id donné dans mcq de la réponse d’un mini-tutoriel.
Attention à l’absurdité : le dictionnaire (unique, évidemment) est imbriqué dans une liste à un élément.

Réponse type :

[{
  "id": 42, /* id du QCM */
  "questions":
    [
      {
        "comment": "Commentaire pour la question",
        "text": "Contenu de la question", /* HTML sans conteneur */
        "id": 420, /* id de la question */
        "answers":
          [
            {
              "text": "Texte de la réponse",
              "id": 4200, /* id de la réponse */
              "is_correct": <true ou false> /* est bonne réponse si vrai */
            }
            , ... /* réponses suivantes */
          ]
      }
      , ... /* questions suivantes */
    ]
}]

Recherche de tutoriels

/search/tutorial/<query>
Effectue une recherche sur l’expression <query> (qui doit être URL-encodée).
Remarquez la structure : les résultats sont classés par catégories, puis par tutoriels.

Réponse type :

[
  {
    "icon": "http://uploads.siteduzero.com/cat/thb/1_1000/70.png",
    "id": 42,
    "title": "Nom de la catégorie",
    "total_element": 1337,
    "tutorial": /* réf. liste de tutoriels */
  }
  , ...
]

Hey.

Permettez-moi de vous raconter ma vie un peu. Début 2010, mon ancien abonnement Orange se terminant, j’ai renouvelé mon engagement dans nouveau forfait chez l’opérateur historique, parce qu’il me proposait des avantages si je ne partais pas, en plus d’un mobile à un euro. Or, certains trouveront peut-être cela étrange, mais j’ai toujours refusé de débourser plus d’un euro dans un mobile. En effet, quand on voit les prix pratiqués par les opérateurs français, il y a de quoi avoir peur. Alors quitte à nous la mettre profonde sur le forfait, je n’allais pas en plus leur autoriser une double pénétration en achetant un appareil à plus de 100€. J’ai donc choisi le mobile en promo à ce moment-là, le Samsung Player One. Un terminal assez sympa, bien que le tactile soit médiocre. Mais son principal défaut réside dans quelque chose de plus gênant.

Un problème de fond

Je ne suis pas un grand fan des appels téléphoniques. Je préfère, comme nombre de personnes, les textos aux communications directes la plupart du temps. Génération TEXTO, comme on dit (oreilles sensibles, s’abstenir de cliquer). J’ai donc choisi un forfait avec SMS illimités. Sauf que voilà, à force de communiquer massivement, les messages s’accumulent vite et la mémoire interne du mobile sature rapidement. Je ne pensais pas que cela était un problème. J’avais en réserve une carte microSD que j’ai inséré dans l’appareil. « Cool, 2Go d’espace supplémentaire, je peux sûrement tenir jusqu’en Décembre 2012. » C’était sans compter les gars de chez Samsung, qui ne se sont pas fait chier à permettre à l’utilisateur de stocker ses SMS sur ce support amovible. On peut y mettre des musiques, des photos, mais pas ses SMS. Me voilà donc bloqué, comme la plupart des utilisateurs du player One, avec 200 messages conservables en tout et pour tout. Je suis un mec social (hoho), ça ne me suffit pas.

Ce n’est sans doute pas si grave. Je suis un mec optimiste et pas blasé pour un sou. Il me vient à l’idée, plutôt que de purger mes messages régulièrement (seule manière d’être en mesure de recevoir de nouveaux SMS), de les vider sur mon PC de temps en temps, histoire de pouvoir garder les plus importants/marrants sous la main. Super, c’est une solution simple et rapide. Et ça ne peut pas merder, tellement c’est une opération facile.

Voilà qui m’apprendra à parler trop vite.

Qu’est ce qui est beau, lourd, inutile et pas fini ?

Transférer du contenu de son mobile vers son ordinateur. Ça paraît simple à première vue. D’autant plus que je possède un PC sous Windows Vista, seule plateforme supportée par les logiciels de nos chers fabricants. Je dégaine donc le CD-Rom d’installation du logiciel de gestion de chez Samsung, joliment appelé PC Studio puis, suite à une mise à jour, New PC Studio – au moins, ils ne se sont pas chier pour le nom. Sans grande surprise, l’installateur est lent, mais il est super joli, avec ses reflets glossy et ses dégradés de la morkitue. Mais tout de même, aviez-vous déjà patienté 26 minutes pour installer un soft de ce type ? Un avant-goût de ce qui m’attendait par la suite. Heureusement, pour passer le temps, il y avait des discussions marrantes sur twitter.

Après une bonne demie-heure à insulter un assistant d’installation qui ne s’intègre pas à mon thème graphique et 165Mo plus tard (haha), le logiciel démarre. À noter au passage que, sans m’avoir demandé mon avis, l’installateur a ajouté une icône sur le bureau, dans la zone de lancement rapide et le logiciel s’est auto-propulsé dans la liste des programmes souvent utilisés (dans le menu démarrer), alors que je ne l’ai encore jamais ouvert. Bien-sûr, il m’a gentillement ajouté un service qui se lance avec Windows, soit-disant pour lancer le logiciel quand un téléphone est connecté au PC. Mais ne partez pas, le meilleur arrive.

Avec une taille pareille, le soft se devait d’avoir une jolie interface et d’être riche en fonctionnalités. Le premier point s’est avéré tout-à-fait vrai. Samsung doit payer davantage ses graphistes que ses développeurs. Au lancement du logiciel, une douce mélodie façon « restez zen, tout va bien » sort de mes enceintes. Sur le coup ça m’a fait un choc, le volume était fort et je ne m’attendais pas à ce qu’un logiciel de gestion de mobiles se la joue Media Center. Passons. La musique accompagne une image animée avec des vagues qui dansent, un peu comme sur la PSP. C’est super joli mais c’est long, mon ventilateur commence à crier et moi, à m’impatienter. Vais-je réussir à transférer mes SMS ?

Quelques secondes plus tard, je me retrouve en face d’un très joli écran d’accueil qui explique le fonctionnement du logiciel. Cool, mais je m’en tape. Ce genre de logiciel se doit d’être intuitif, je ne veux pas me taper les 5 catégories du tutoriel pour faire un misérable transfert. Heureusement, il y a une petite croix pour fermer la chose. Et là c’est le drame, le tutoriel se ferme mais rien d’autre n’apparaît. Mon sang a le temps de faire un tour avant qu’enfin, une fenêtre s’affiche. Nous y voilà. L’interface recréé une sorte de bureau avec un dock en bas. On peut ajouter des sections à ce bureau virtuel, genre un explorateur de fichiers qui ne fonctionne pas ou un lecteur vidéo. Ouais, un lecteur vidéo dans un logiciel pour gérer son mobile. Y’a aussi un programme de gravure et d’affichage d’images. Je commence à comprendre la taille du logiciel.

Ne voilà-t-il pas que le programme m’affiche une notification pour le moins bruyante : « mise à jour disponible. » Je suis rassuré, il y a au moins une procédure de mise à jour automatique, c’est un effort notable. Je me précipite sur le bouton correspondant. La fenêtre prend cinq bonnes secondes à s’afficher, je vous laisse admirer le résultat. On voit que ç’a été conçu en anglais, puis traduit par la suite. Les textes sortent des boutons et certains mots sont illisibles. Très pratique. Le bouton Détails affiche un dialogue vide. Encore plus pratique. Vive la transparence sur ce que j’installe. Peu importe, on est plus à ça près, je lance la mise à jour. Alors là, je dois dire que ça marche plutôt bien. Si l’on exclut les 38 minutes pour télécharger 85Mo avec une connexion ADSL, c’est de la bombe. Tout ça pour avoir une interface légèrement retouchée et zéro fonctionnalité supplémentaire. Un peu comme une nouvelle version de Windows – mais non, je ne troll pas. Me voilà donc finalement avec la nouvelle mouture du programme. Cool, je vais pouvoir faire mon transfert. Ou pas. Ne voilà-t-il pas que je reçois la même notification de mise à jour. À croire qu’ils ne savent pas faire de patchs cumulatifs. C’est reparti pour une demie-heure, 136Mo et dix autres minutes pour que l’installateur « recherche les fonctionnalités déjà installés » (oui, chez Samsung c’est un fonctionnalité) ; elles devaient être bien cachées. Heureusement, j’avais des maths à faire.

Après mes deux mises à jours, j’ai finalement réussi à synchroniser mon mobile avec le PC. Cela s’est passé sans encombres, heureusement. Du coup, j’ai décidé de faire un peu le tour du propriétaire, histoire de voir si cette chose méritait ses 185Mo.

Je n’ai pas été déçu. Je savais que la tendance qu’ont les industriels à faire des logiciels très user-friendly résulte dans des logiciels fondamentalement mauvais. Mais je ne pouvais pas concevoir quelque chose d’aussi inutile et lourd. Ne faisons pas cas des applications futiles du truc, comme le soft de gravure ou de lecture vidéo. Le Player One est un portable multimédia, ça passe encore. En fait, là où j’ai le plus rigolé (façon de parler) c’est quand j’ai ouvert les préférences de PC Studio. Cliquez pour admirer :

Sur le premier panel, une option concernant les effets sonores. Sérieusement, à quoi bon se faire chier à mettre des sons dans un logiciel de gestion de mobile ? On notera tout de même qu’on peut, au moins, les désactiver. Mais le plus ridicule reste, à mon sens, ce deuxième onglet. Tout un tas de paramètres liés, quoi ? au thème graphique du bureau virtuel. On peut même choisir une image de fond grâce à leur explorateur fait maison (je vous raconte pas le massacre). Non sérieusement, qu’est-ce que ça peut nous faire de changer la couleur d’arrière-plan d’un logiciel dont on se servira trois fois par an et dont le but n’est pas de fournir une interface jolie mais un système rapide, efficace et fonctionnel pour gérer ses contacts, ses messages et ses fichiers multimédias. Et bien non, ces fonctionnalités sont certes présentes mais plantent régulièrement et n’offrent aucun avantage lié à l’utilisation d’un ordinateur – manipulation des fichiers plus en détail par exemple. Mais hey, dude, tu peux changer le fond d’écran. T’inquiète, c’est juste la classe.

Non, vraiment, Samsung (New) PC Studio n’est pas un logiciel. C’est seulement quelques outils intéressants perdus dans un monceau de kikooleries qui le rendent lourd et lent. Mais c’est beau, ça plaît au client. Y’a des popups animés et des sons à la con. Dans la vidéo d’introduction, t’as le logo du logiciel qui bouge pendant 17 secondes avant d’avoir accès aux rubriques d’aide.

Samsung, je te chie dessus. Il m’a fallu une demie-journée pour sauvegarder 200 SMS parce que ton mobile a une mémoire/un firmware de merde et ton logiciel est un incommensurable tas de purin.