InvaZion

Comprendre les résultats renvoyés par les API

Pages liées :

• 3 méthodes pour créer votre propre version du jeu
• Liste complète des API du jeu

Principe général

Toutes les API du jeu respectent la même structure générale. Elles contiennent toutes deux noeuds principaux :

• [metas], qui contient des informations générales (numéro de version de l'API, message d'erreur...). Les clés qu'elle contient sont les mêmes dans toutes les API.
• [datas], qui contient les données demandées (ex : les données de la carte). Contrairement à la clé [metas], la structure de la clé [data] varie selon l'API qui a été appelée. Par exemple, dans l'API "maps", la clé datas contiendra les données relatives à la carte tandis que, dans l'API "citizens", la clé datas contiendra les données relatives aux citoyens.

Structure détaillée des API

Les API sont toutes structurées ainsi :

• metas
  • api_status
  • api_version
  • api_newest_version
  • timestamp
  • error_code
  • error_class
  • error_message
  • error_details
• datas
  • ...

Clés liées à la version de l'API

metas > api_status indique le niveau de stabilité de l'API. Trois valeurs sont possibles :

• stable : l'API est stable, vous pouvez l'utiliser sans rique. En cas d'évolution, nous garantissons que la nouvelle API restera compatible avec l'ancienne (versioning sémantique).
• unstable : l'API est en cours de développement, elle est susceptible de subir des modifications qui « cassent » la compatibilité. Nous avons utilisé ce statut au début du développement du jeu afin de ne pas ralentir le développement, il ne devrait plus être utilisé à l'avenir.
• deprecated : cette version de l'API est obsolète et ne devrait plus être utilisée. Elle n'est maintenue que pour assurer que les applications existantes qui l'utilisent continuent de fonctionner.

metas > api_version indique le numéro de version de l'API que vous utilisez (ex : 1.0). Chaque API (maps, citizens, zone...) a son propre numéro de version car elles n'évoluent pas toutes à la même fréquence.

metas > api_newest_version indique le numéro de la version la plus récente de l'API (ex : 2.0). En comparant les valeurs de api_version et api_newest_version, vous pouvez détecter si une version plus récente de l'API est disponible. Si vous utilisez déjà la version la plus récente de l'API, les deux clés ont la même valeur.

Clés liées à la date

> timestamp indique le moment où la page a été générée, à la seconde près, sous forme d'un timestamp Unix. Le timestamp Unix représente une date sous forme d'un nombre unique, correspondant au nombre de secondes écoulées depuis le 1^er janvier 1970. Par exemple, le timestamp 1602429478 correspond au 11 octobre 2020 à 15h17mn58s.

Cette clé est utile pour charger intelligemment les données, en ne récupérant que les données du jeu qui ont été modifiées depuis le dernier appel à l'API : voir la documentation des API du jeu (notamment le paramètre &newerthan).

Clés de gestion des erreurs

metas > error_code contient un code d'erreur textuel indiquant que l'action que vous avez demandée au moyen de l'API a réussi ou la raison pour laquelle elle a échoué.

• Si l'action a réussi, le code sera toujours success, quelle que soit l'API.
• Si l'action a échoué, le code d'erreur dépendra de l'API appelée. Par exemple, l'API qui permet d'attaquer un zombie à mains nues retournera le code no_zombies_here s'il n'y a aucun zombie dans la zone.

Les noms des codes d'erreur sont stables, ils ne seront pas modifiés à l'improviste. Vous pouvez vous baser sur eux pour vos traitements (ex : Si code d'erreur est XXX, alors afficher le message YYY).

metas > error_class indique le niveau de gravité de l'erreur signalée par la clé [error_code] (voir plus haut). Cette information sera très pratique pour vous si vous affichez les messages différemment selon leur nature (ex : les messages d'information en vert, les messages d'avertissement en rouge). La clé error_class contient une de ces trois valeurs :

• info : le résultat signalé par error_code est de nature « positive » Ex : l'action a totalement réussi.
• warning : le résultat est de nature « négative ». Ex : le citoyen a tenté se déplacer, mais il n'a pas pu car il est bloqué par les zombies. Vous pouvez choisir d'afficher les erreurs "warning" en rouge pour vous assurer que le joueur les verra.
• critical : une erreur d'ordre technique est survenue. Ces erreurs sont anormales et ne devraient jamais se produire. Trois origines possibles :
  • Bug dans le code de votre site ou application. Par exemple, vous avez oublié un paramètre obligatoire en appelant une API. Si vous ne comprenez pas d'où vient le problème, n'hésitez pas à demander de l'aide sur le forum d'InvaZion.
  • Erreur dans la conception de votre interface. Par exemple, vous affichez au joueur le bouton « Entrer en ville » alors qu'il n'y a aucune ville dans sa zone. Ajoutez une condition pour masquer le bouton lorsqu'il n'est pas utilisable.
  • Plus rarement, le problème peut provenir du serveur central d'InvaZion (ex : le serveur est inaccessible). Vous pouvez signaler ces incidents sur le forum d'InvaZion.

metas > error_message contient un message textuel destiné au joueur, décrivant le résultat de son action (ex : « Vous avez découvert l'objet X »). Vous pouvez intégrer ce texte directement dans votre application. Cela vous épargne de définir un par un les messages associés à chaque code d'erreur (voir ci-dessus, la clé error_code).

metas > error_details contient un message textuel qui précise les détails techniques en cas de bug. Il est destiné à vous, développeur, pour vous permettre de corriger les erreurs que vous avez pu commettre en appelant l'API (par exemple, si vous demandez les données d'une carte mais oubliez d'indiquer le numéro de la carte que vous voulez récupérer). Le message contenu dans error_message (voir ci-dessus) est plus succinct et vague que celui de error_details afin de ne pas noyer le joueur dans des détails techniques qu'il ne comprendrait pas.
Il se peut que error_details ne soit pas renseigné si le message de error_message est déjà suffisamment clair.

Clés contenant les données

Les données retournées par l'API se trouvent dans la clé datas. Son contenu va dépendre de quelle API vous avez appelée. Par exemple, l'API Maps affiche les données de la carte (position des zombies...) tandis que l'API Citizens affiche les données concernant les joueurs (nombre de points d'action...).

Pour connaître les API disponibles et savoir ce qu'elles renvoient, consultez la liste complète des API du jeu.