Dear users,
we are looking for boardgaming enthusiast that would be willing to help us on occasional basis to improve this website. The main focus should be polish localization of functional text (not the articles / content - at least at the beginning). We believe it should take like tens of minutes per week at most. If you are willing to help (or just try :-), please contact us with this form.

Contact us Any help is more than appreciated...

Dokumentace API

Zatrolené hry nabízí přístup k některým svým údajům o hrách a dalších funkcích pomocí programatického API. Pokud chcete tato API využívat, kontaktujte nás, protože jsou všechna API zabezpečena a jejich použití je měřeno, aby třeba jejich nevhodnou integrací nedocházelo ke snížení výkonu hlavních stránek Zatrolených her.

Obsah

  1. Zabezpečení API
  2. Dostupné metody
    1. @game-get-by-ean
    2. @game-get-by-id

Zabezpečení API

Pro volání všech metod našeho API budete potřebovat vlastní APPID (identifikátor aplikace, která API využívá) a k němu privátní klíč, kterým bude aplikace svá volání podepisovat. Pro jejich získání nás kontaktuje.

Každé volání API obsahuje 3 parametry, které souvisí s jejich zabezpečením

  • appid [string] [required] - identifikátor aplikace, která API volá
  • tm [integer] [required] - timestamp okamžiku volání API v UNIX formátu (tedy počet sekund od 1.1.1970). Používá se pro zabezpečení API a žádný request nesmí mít hodnotu tohoto atributu starší než 15 vteřin.
  • hmac_sign [string] [required] - podpis volání API pomocí privátního klíče aplikace, která API volá.

Jak vygenerovat správný podpis?

Podpis se generuje dle standardu HMAC-SHA1 z (1) URL volání API a (2) privátního klíče aplikace.

Předpokládejme, že pro naší aplikaci máme vygenerované appid "demo" s privátním klíčem "demo_secret". A chceme volat metodu s umístěním "www.zatrolene-hry.cz/api/demo-metoda" a jedním vstupním parametrem "parametr" s hodnotou "abc".

  1. Bez zabezpečení bychom zavolali "http://www.zatrolene-hry.cz/api/demo-metoda?parametr=abc".
  2. Nejprve přidáme parametry appid a tm. Výsledkem tedy získáme "http://www.zatrolene-hry.cz/api/demo-metoda?parametr=abc&appid=demo&tm=1410808225" (nezapomeňte parametr tm naplnit aktuálním časem).
  3. Pro podpis z adresy odstraníme definici protokolu a adresu serveru. Pro podpis nám tedy zůstane tento otisk volání "/api/demo-metoda?parametr=abc&appid=demo&tm=1410808225".
  4. Tento otisk zašifrujeme pomocí HMAC-SHA1 a privátního klíče aplikace. Např. v jazyce PHP se jedná o funkci "hash_hmac()" a v tomto případě by její zápis vypadal následovně: hash_hmac("sha1", "/api/demo-metoda?parametr=abc&appid=demo&tm=1410808225", "demo_secret");
  5. Výsledný řetězec znaků přidáme k volání API jako hodnotu parametru hmac_sign. Tedy "http://www.zatrolene-hry.cz/api/demo-metoda?parametr=abc&appid=demo&tm=1410808225&hmac_sign=0d11e467defa75544341aa62aac828cfc50dc6f4"
  6. Tím máme hotovo a můžeme vesele volat dané API.

Dostupné metody

@game-get-by-ean

Tato metoda slouží pro získání základních informací o hře na základě jejího EANu (čárového kódu). Mezi tyto vrácené informace patří např. název hry, průměrné hodnocení atp.

Umístění: www.zatrolene-hry.cz/api/game-get-by-ean

HTTP metoda: GET

Vstupní parametry:

  • ean [integer] [required] - čárový kód hry, ke které chcete získat informace
  • game [string] [optional] - název hry, který slouží pro případ, že použitý EAN není v databázi ZH. Průběžně budeme tyto neznámé EANy procházet a pak tento název hry použijeme pro přidání EANu ke hře.
  • format ["xml"] [optional] - použitím tohoto parametru si můžete vynutit odpověď ve formátu XML. Pokud ho nepoužijete nebo nastavíte hodnotu na jinou než "xml", vrátí se odpověď ve formátu JSON.
  • appid (viz Zabezpečení API)
  • tm (viz Zabezpečení API)
  • hmac_sign (viz Zabezpečení API)

Formát odpovědi: Jedná se o JSON nebo XML formát pole o 2 hlavních sekcích.

  • status - informace o stavu zpracování volání. Skládá se z code, který nabývá hodnot 1 (vše proběhlo v pořádku) nebo -1 (došlo k chybě) a message, která se objevuje primárně při chybě ve zpracování volání s popisem, k čemu došlo.
  • game - informace o samotné hře. V odpovědi je pouze pokud se podaří úspěšně nalézt odpovídající hru.

Příklady volání:

  • http://www.zatrolene-hry.cz/api/game-get-by-ean?ean=9781589942868&appid=demo&tm=1410808225&hmac_sign=06025fff343ca90ae1badbb805ea7236e4765b28 (vrátí odpověď ve formátu JSON)
  • http://www.zatrolene-hry.cz/api/game-get-by-ean?ean=9781589942868&format=xml&appid=demo&tm=1410808225&hmac_sign=1096f759bca2aa10b9d0fbd9a86356e8242e715a (vrátí odpověď ve formátu XML)

Příklad odpovědi:

{
   "status":{
      "code":1
   },
   "game":{
      "id":1,
      "name":"Arkham Horror",
      "url":"http:\/\/www.zatrolene-hry.cz\/spolecenska-hra\/arkham-horror-1\/",
      "rating":{
         "avg":8.64696485623,
         "votes":626
      }
   }
} 

@game-get-by-id

Tato metoda slouží pro získání základních informací o hře na základě jejího ID na Zatrolených hrách. Mezi tyto vrácené informace patří např. název hry, průměrné hodnocení atp.

Umístění: www.zatrolene-hry.cz/api/game-get-by-id

HTTP metoda: GET

Vstupní parametry:

  • zhgameid [integer] [required] - identifikátor hry na Zatrolených hrách, ke které chcete získat informace (např. Arkham Horror má ID = 1)
  • format ["xml"] [optional] - použitím tohoto parametru si můžete vynutit odpověď ve formátu XML. Pokud ho nepoužijete nebo nastavíte hodnotu na jinou než "xml", vrátí se odpověď ve formátu JSON.
  • appid (viz Zabezpečení API)
  • tm (viz Zabezpečení API)
  • hmac_sign (viz Zabezpečení API)

Formát odpovědi: Jedná se o JSON nebo XML formát pole o 2 hlavních sekcích.

  • status - informace o stavu zpracování volání. Skládá se z code, který nabývá hodnot 1 (vše proběhlo v pořádku) nebo -1 (došlo k chybě) a message, která se objevuje primárně při chybě ve zpracování volání s popisem, k čemu došlo.
  • game - informace o samotné hře. V odpovědi je pouze pokud se podaří úspěšně nalézt odpovídající hru.

Příklady volání:

  • http://www.zatrolene-hry.cz/api/game-get-by-id?zhgameid=1&appid=demo&tm=1410808225&hmac_sign=7de6fb37c5b8683846dd5e57788b12c8ebc05c20 (vrátí odpověď ve formátu JSON)
  • http://www.zatrolene-hry.cz/api/game-get-by-id?zhgameid=1&format=xml&appid=demo&tm=1410808225&hmac_sign=2fd6db40853c0b3b05a95aab2c38770115ccc98c (vrátí odpověď ve formátu XML)

Příklad odpovědi:

{
   "status":{
      "code":1
   },
   "game":{
      "id":1,
      "name":"Arkham Horror",
      "url":"http:\/\/www.zatrolene-hry.cz\/spolecenska-hra\/arkham-horror-1\/",
      "rating":{
         "avg":8.64696485623,
         "votes":626
      }
   }
} 

Miejsce dyskusji

No discussions...