API

"La page qui interface..."

Description

L’API JAC est un service Web à destination des développeurs. Son accès est libre, gratuit, complet et ne nécessite aucune démarche pour être utilisé (pas même d’inscription ou d’ouverture de comptes…). Le nombre d’appel est seulement limité pour éviter une utilisation abusive, mais reste largement suffisante pour une utilisation normale.

Utilisation

Pour utiliser l’API, il suffit d’envoyer une requête en POST à l’adresse : http://www.jeux-alternatifs.com/API.php. Nous verrons par la suite, un exemple en PHP.

En retour, vous obtiendrez une réponse structurée au format JSON. Cette réponse contient 2 tableaux : le conteneur qui contient des informations communes à chaque fonction de l’API et le contenu qui contient les informations demandées.

Conteneur

Le conteneur contient 2 éléments :

• reponse (entier) : code qui indique la validité de votre appel ou la raison de son échec.
• nbAppelRestant (entier) : nombre d’appel restant de l’API avant de devoir attendre le lendemain.

reponse

La rubrique « reponse » peut contenir les valeurs suivantes :

• Valide : 100
• Erreur :
• 200 : fonction de l’API inconnue
• 201 : nb d’appel maximum par jour atteint
• 300 : date non valide
• 301 : date trop ancienne (3 jours maximum)
• 302 : id jeu inconnu
• 303 : nombre d’IP maximum dépassé
• 304 : une ou plusieurs IP invalides

nbAppelRestant

La rubrique « nbAppelRestant » affiche le nombre d'appel qui vous reste avant de devoir attendre le lendemain pour, de nouveau, pouvoir consommer l’API.
Actuellement, vous pouvez appeler 100 fois l’API par jour.

Fonction IPVote

Actuellement, l’API JAC ne contient qu’une seule fonction : IPVote. Comme son nom le laisse supposer. Elle permet de savoir si une IP a voté ou non pour un jeu sur un jour précis.

Imaginons que vous stockez l’IP des joueurs cliquant sur un lien « Voter sur JAC » présent sur votre site. Le lendemain matin, vous utilisez un CRON (script automatique) qui appelle l’API JAC avec la liste des IP de la veille. Aussitôt, vous savez quels sont les joueurs qui ont réellement voté après avoir cliqué sur votre lien et ainsi les récompenser précisément.

Appel

L’appel d’IPVote contient 4 paramètres :

• nomFonction (chaîne) : « IPVote »
• idJeu (entier) : identifiant du jeu. Pour connaître cet identifiant, vous pouvez afficher la fiche de votre jeu et observer l’URL. Le chiffre a côté de « jeu » est l’identifiant. Par exemple : le jeu « Woshu Moshu » porte l’identifiant 123.
• dateVote (date AAAA-MM-JJ) : date du contrôle. Attention, vous ne pouvez contrôler le vote d’IP que sur les 3 derniers jours.
• IP (tableau de chaîne) : liste des IP à contrôler. Ce tableau peut contenir un maximum de 100 IP. Ainsi, avec les 100 appels possibles par jour, vous pouvez contrôler au maximum 10000 IP par jour.

Réponse

En plus du conteneur vu précédemment, la réponse à votre appel contient un tableau contenu propre à la fonction IPVote.

• Contenu (tableau)
• IP (tableau)
• IP (chaîne) : IP
• etatVote (entier) = 1 : à voté, 2 : n’a pas voté
• heureVote (heure HHMMSS) : heure du vote ou absent si etatVote=2

Exemple en PHP

Le script PHP ci-dessous interroge l’API JAC en lui demandant si les IP 192.168.0.1, 192.168.0.2 et 192.168.0.3 ont voté pour le jeu Antaris Legacy (identifié sur JAC par l’identifiant 736) le 20 juin 2014.

$postdata = http_build_query(
    array(
		'nomFonction' => 'IPVote',
		'idJeu' => 736,
		'dateVote' => '2014-06-20',
		'IP' => array('192.168.0.1','192.168.0.2','192.168.0.3')
    )
);

$opts = array('http' =>
    array(
        'method'  => 'POST',
        'header'  => 'Content-type: application/x-www-form-urlencoded',
        'content' => $postdata
    )
);

$context  = stream_context_create($opts);

$result = file_get_contents('http://www.jeux-alternatifs.com/API.php', false, $context);

// affiche la réponse en JSON
echo $result;

// converti la réponse JSON en tableau PHP
echo "<pre>";
print_r(json_decode(substr($result,3))); // explication : http://ios4vn.com/?p=46
echo "</pre>";

Ce script pourrait retourner un tableau PHP similaire à celui-ci-dessous :

stdClass Object
(
    [conteneur] => stdClass Object
        (
            [reponse] => 100
            [nbAppelRestant] => 85
        )
    [contenu] => stdClass Object
        (
            [IP] => stdClass Object
                (
                    [192.168.0.1] => stdClass Object
                        (
                            [etatVote] => 2
                        )
                    [192.168.0.2] => stdClass Object
                        (
                            [etatVote] => 1
                            [heureVote] => 00:00:52
                        )
                    [192.168.0.3] => stdClass Object
                        (
                            [etatVote] => 2
                        )
                )
        )
)