Hordes : L'API XML

L'API XML a été développée par Deepnight sur demande des joueurs de la première version bêta.

Rien n'est encore définitif. Les choses peuvent évoluer, des informations pourront être ajoutées et d'autres pourront disparaître.

L'API XML permet d'avoir un accès en lecture à certaines informations de la ville. Son exploitation peut se faire sur différents supports : Site Web, Applications, DS, iPhone, Mobile, Palm, ….

Vous trouverez l'aide officielle (hordes.fr) de l'API XML là ⇒ .

Pour information, la version actuelle du flux XML est 2.171.

Le XML v2 a changé sur de nombreux points.
Tout d'abord la structure, voyons un exemple simple de la v2 :

  <hordes>
    <headers link="http://beta.hordes.fr/xml" iconurl="http://data.hordes.fr/gfx/icons/" secure="0"
    author="Motion Twin http://www.motion-twin.fr" language="fr" version="2.10"
    avatarurl="http://imgup.motion-twin.com/" generator="haxe">
    <owner>
      <citizen dead="0" hero="0" name="DarKalimHero" x="9" y="4" id="666" ban="0" job="basic" out="1"
      baseDef="0">
      </citizen>
      <myZone .../>
    </owner>
    <game days="5" quarantine="0" datetime="2009-01-08 21:48:28" id="159269"/>
    </headers>
    <data cache-date="2008-11-03 16:11:19" cache-fast="0">
      <city .../>
      <bank .../>
      <expeditions.../>
      <citizens .../>
      <cadavers .../>
      <map .../>
      <upgrades .../>
    </data>
  </hordes>

Les infos “ban” et “dead” sont passées dans la node <owner/> qui se trouve dans <headers/>.
La node <game/> est déplacée dans <headers/>
Toutes les infos de jeu (banque, carte, citoyens…) sont rangées dans une node <data/>.

La node <city/> s'enrichi d'une nouvelle node <defense/> qui contient le détail complet des défenses de la ville :

  <defense base="5" items="39" citizens="1" upgrades="0" buildings="0" total="84" itemsMul="2"/>

base = défense initiale d'une ville
citizens = défense apportée par les citoyens (maison, travaux et bonus gardiens)
upgrades = défense apportée par les évolutions
buildings = défense apportée par les chantiers
items x itemsMul = défense des objets en banque (nombre x multiplicateur)

La node <data/> dispose de 2 attributs :
- le mode “cache-fast” (0 ou 1), nous y reviendrons,
- la date de dernière actualisation du cache.

La node <upgrades/> contient des nodes <up/> comme par exemple :

  <upgrades total="4">
    <up name="Atelier" level="1"/>
    <up name="Pompe" level="3"/>
    ...
  </upgrades>

L'attribut “total” est simplement le nombre total de niveaux d'évolutions.

Seules les données présentes dans <data/> sont concernées par la mise en cache.
Les données dans <headers/> sont toujours à jour, en temps réel.
Les infos que vous recevez sont mises à jour au maximum toutes les 5 minutes en mode “cache-fast” à 0, et toutes les minutes en mode “cache-fast” à 1.

Vous bénéficiez du mode “cache-fast” si vous en faites la demande.
Une clé unique pour votre site vous est alors attribuée, il suffit dès lors de l'envoyer avec votre requête pour récupérer le XML :

http://www.hordes.fr/xml?k=[api_key];sk=[site_key]

IMPORTANT : vous devez garder cette clé secrète ! Elle pourra être régénérée sur demande.

Les sites externes disposant d'une clé (voir ci-dessus) peuvent demander à passer en “mode sécurisé”.

Ce mode permet de recevoir une node <owner/> dans <headers/> qui donne le login du joueur, s'il est banni et s'il est mort.
IMPORTANT : les sites sans mode sécurisé n'auront pas ces infos !

Un site utilisant le mode sécurisé doit obligatoirement être accédé via l'annuaire de Hordes.fr ().
Une clé unique vous est alors envoyée en POST lors de l'appel de votre site. Il vous suffit d'effectuer les requètes, accompagnées de votre clé de site.
Les clés sécurisées seront reconnues et vous recevrez un XML avec la node <owner/> en cadeau.

Cela implique que vous ne pourrez plus avoir de formulaire de connexion du type ”Entrez votre clé API + login”.
Seul le site Hordes.fr pourra vous fournir une clé, via l'annuaire.

La clé en question est issue d'une combinaison entre votre clé site + la clé utilisateur. Cela signifie qu'une clé de “deepnight” sur HordesM@P ne sera pas la même qu'une clé de “deepnight” sur Poste de Contrôle.

Vous pouvez dorénavant appeler une URL de demande de XML en ajoutant le paramètre “comment=1” à l'URL.
Vous recevrez en réponse un XML dont les valeurs ne seront pas exploitables, mais qui sera commenté.

http://www.hordes.fr/xml?k=[api_key];comment=1
ou
http://www.hordes.fr/xml?k=[api_key];sk=[site_key];comment=1

Exemple de node commentée :

  <building
    name="String"
    temporary="1/0 (vaut 1 si le chantier doit être détruit lors de la prochaine attaque)"
    id="Int"
    img="String">
    .....CDATA.....
  </building>

Vous pouvez ainsi connaître le type de chaque attribut (entier, flottant, chaîne de caractères, date…) et éventuellement un commentaire pour les cas qui nécessitent une explication.

Certaines nodes peuvent ne pas apparaître selon le flux XML.
Par exemple, s'il n'y aucune évolution de réalisée dans la ville concernée, la node <evolutions/> sera vide et par conséquent non-commentée.

ATTENTION : cet appel passe outre le cache et ne doit pas être utilisé massivement (auquel cas la MT serait obligée de le désactiver). Il a pour seul but de permettre d'obtenir une ébauche de documentation automatique de n'importe quel XML.

Cette option n'est plus possible.

Chaque paire utilisateur + site disposant d'une clé unique, il vous est impossible de rediriger un visiteur authentifié sur votre site vers un autre site externe (vous ne connaissez pas la clé correspondante).

Vous pouvez néanmoins le faire en utilisant l'URL de “bounce” proposée par Hordes.
Cette URL ne peut être appelée que par un site externe disposant d'une clé API utilisateur “authentifiée” :

http://beta.hordes.fr/bounce?k=[api_key];to=[destination_id]

[api_key] : clé authentifiée de l'utilisateur.
[destination_id] : id du site vers lequel vous souhaitez être redirigé(e).
Optionnel : ajoutez l'attribut “redir=1” si vous souhaitez être redirigé(e) automatiquement sans passer par la page “disclaimer”.

Vous trouverez sur cette même page toute la documentation nécessaire pour comprendre et utiliser le bounce.

Ceci était un communiqué de notre cher Administrateur Deepnight.

Concernant l'API, l'accès se fera sur l'adresse :

www.hordes.fr/xml?k=[api_key]

Le champ [api_key] est généré depuis la page Réglages dans Mon âme : un identifiant unique anonyme pour chaque utilisateur.

L'appel à cette adresse renverra directement un flux XML complet de toutes les informations de la ville, des joueurs et de l'outre-monde.

  <headers link="http://www.hordes.fr" iconurl="http://data.hordes.fr/gfx/icons/" secure="0"
    author="Motion Twin http://www.motion-twin.fr/" language="fr" version="2.10"
    avatarurl="http://imgup.motion-twin.com/" generator="haxe">
    <!-- Optionnel : node 'owner' en mode XML sécurisé -->
    <game days="1" quarantine="0" datetime="2008-12-24 23:59:59" id="666"/>
    <owner>
      <citizen dead="0" hero="0" name="DarKalimHero" x="9" y="4" id="666" ban="0" job="basic" out="1"
      baseDef="0">
      </citizen>
      <myZone .../>
    </owner>
  </headers>

Le nœud error apparaît quand il y a une erreur ou une cause qui fait que les informations ne seront pas délivrées.

  <error code="user_not_found"/>

En mode sécurisé, on peut obtenir le nom de l'utilisateur dans certaines erreurs :

  <error code="not_in_game" name="Le Corbeau" id="2" hero="1"/>

Le nœud owner apparaît lorsque le XML est un XML sécurisé (attribut secure=1 dans la node headers).

  <owner>
    <citizen dead="0" hero="0" name="DarKalimHero" x="9" y="4" id="666" ban="0" job="basic" out="1" baseDef="0">
    </citizen>
    <myZone dried="0" z="3" h="2">
      <item name="Ouvre-boîte" count="1" id="23" img="can_opener" broken="1"/>
    </myZone>
  </owner>

  <game days="1" quarantine="0" datetime="2008-12-24 23:59:59" id="666"/>

  <data cache-date="2008-11-24 21:41:48" cache-fast="0">
    <city city="Vallée ravagée" door="1" hard="0" water="34" chaos="1" devast="1" x="19" y="10">
      <defense base="5" items="0" citizen_guardians="1" citizen_homes="0" upgrades="0" buildings="0"
      total="6" itemsMul="2"/>
    </city>
    <bank>
      <item name="Poignée de vis et écrous" count="1" id="41" cat="Rsc" img="meca_parts" broken="0"/>
    </bank>
    <expeditions/>
    <citizens>
      <citizen dead="0" hero="0" name="Test" avatar="hordes/e/e/6a66a66a_66.jpg" x="9" y="4" id="666" ban="0"
      job="basic" out="1" baseDef="0"></citizen>
    </citizens>
    <cadavers/>
    <map hei="14" wid="14">
      <zone x="9" y="4" nvt="0" tag="6" danger="2"/>
      <zone x="7" y="2" nvt="0" tag="1" danger="3">
        <building name="Bâtiment non-deterré" type="-1" dig="19"/>
      </zone>
    </map>
    <upgrades total="0"/>
    <estimations/>
  </data>

  <city city="Vallée ravagée" door="1" hard="0" water="34" chaos="1" devast="1" x="19" y="10">
    <building name="Tour de guet" temporary="0" id="1050" img="item_tagger">
      Cette tour placée près de l'entrée offre une estimation de l'attaque du soir et permet ainsi aux
      citoyens de mieux s'y préparer. Elle débloque également toutes les constructions liées aux 
      situations d'urgence.
    </building>
    <building name="Portail" temporary="0" id="1062" img="small_door_closed">
      Un bricolage un peu rustique qui permet d'empêcher l'ouverture (rarement désirée) de la porte de 
      23h40 à minuit. La porte doit toutefois toujours être fermée manuellement.
    </building>
    <news z="24">
      <content>
        <p>2 citoyens manquent à l'appel ce matin... Ils sont sortis cette nuit... 
        Mais pas un seul n'est revenu... <strong>Pas UN SEUL</strong>.</p><p>A part 
        ça, nos défenses ont suffi pour résister cette nuit. Je doute que ça soit aussi 
        bien ce soir, les zombies vont vraiment avoir les crocs...</p>
      </content>
    </news>
    <defense base="5" items="1" citizen_guardians="1" citizen_homes="3" upgrades="0" buildings="5"
    total="16" itemsMul="2"/>
  </city>

  <bank>
    <item name="Pile" count="9" id="2" cat="Rsc" img="pile" broken="0"/>
 
    <item name="Boîte de Conserve ouverte" count="7" id="4" cat="Food" img="can_open" broken="0"/>
    <item name="Tournevis" count="2" id="14" cat="Weapon" img="screw" broken="0"/>
    ...
  </bank>

  <expeditions>
    <expedition name="Expédition jour 3 [4PA]" author="Xiiwit" length="4" authorId="17057">
      <point x="6" y="6"/>
      <point x="5" y="6"/>
      <point x="5" y="5"/>
      <point x="6" y="5"/>
    </expedition>
    ...
  </expeditions>

<citizens>
   <citizen dead="0" hero="1" name="DarKalimHero" avatar="hordes/a/2/49329743_19903.jpg" x="8" y="7" id="19903" ban="0" job="guardian" out="1" baseDef="0"></citizen>
            <citizen dead="0" hero="1" name="darkMK" avatar="hordes/5/5/a6b5ca88_85114.jpg" x="11" y="6" id="85114" ban="0" job="hunter" out="0" baseDef="0"></citizen>
            <citizen dead="0" hero="0" name="Dimedolorole" avatar="hordes/9/d/ca33d9b3_387943.jpg" x="12" y="5" id="387943" ban="0" job="basic" out="1" baseDef="1">Quel style, quel style !</citizen>
            <citizen dead="0" hero="0" name="emua" avatar="hordes/2/c/cdc390a8_339438.jpg" x="11" y="6" id="339438" ban="0" job="basic" out="0" baseDef="0"></citizen>
...
</citizens>

  <cadavers>
    <cadaver name="Haoshin" dtype="5" id="6144" day="1">
      <msg>
        <![CDATA[Message de mort]]>    
      </msg>
    </cadaver>
    <cadaver name="Thesavantfou" dtype="5" id="36826" day="1">
      <cleanup type="garbage" user="Brounie"/>
      <msg>
        <![CDATA[]]>
      </msg>
    </cadaver>
    ...
  </cadavers>

  <map hei="12" wid="12">
    <zone x="5" y="0" nvt="1"/>
    <zone x="6" y="0" tag="4" danger="3" nvt="0">
      <building name="Abris anti-atomique" type="10" dig="0">
        Le numéro est à moitié effacé, mais il s'agissait vraisemblablement de
        l'<strong>abris 14</strong>. Si on en juge par les corps décrépis à l'intérieur, 
        le système de fermeture du sas <strong>n'a pas dû fonctionner comme prévu</strong>.
        Ca arrive.
      </building>
    </zone>
    <zone x="7" y="0" nvt="1"/>
    <zone x="8" y="0" nvt="1"/>
    <zone x="5" y="1" nvt="1"/>
    <zone x="6" y="1" danger="2"/>
    ...
  </map>

Attention: les cases jamais explorées n'apparaissent pas dans le flux (pas de noeud <zone x=“X” y=“Y” /> correspondant)