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
- Zabezpečení API
- Dostupné metody
- @game-get-by-ean
- @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 "https://www.zatrolene-hry.cz/api/demo-metoda"
a jedním vstupním parametrem "parametr" s hodnotou "abc".
- Bez zabezpečení bychom zavolali "https://www.zatrolene-hry.cz/api/demo-metoda?parametr=abc".
- Nejprve přidáme parametry appid a tm. Výsledkem tedy získáme "https://www.zatrolene-hry.cz/api/demo-metoda?parametr=abc&appid=demo&tm=1410808225"
(nezapomeňte parametr tm naplnit aktuálním časem).
- 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".
- 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");
- Výsledný řetězec znaků přidáme k volání API jako hodnotu parametru hmac_sign.
Tedy "https://www.zatrolene-hry.cz/api/demo-metoda?parametr=abc&appid=demo&tm=1410808225&hmac_sign=0d11e467defa75544341aa62aac828cfc50dc6f4"
- 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í: https://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í:
- https://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)
- https://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í: https://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í:
- https://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)
- https://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
}
}
}
