CWG API dokumentace

Verze specifikace
1.3.0
Poslední změna
26.12.2013
Autor
Niximor <niximor@gmail.com>

Jedná se o zastaralou verzi API, která již není udržována. Aktuální verzi API s kompletní dokumentací naleznete zde zde.

Obsah

  1. Úvod
  2. Podmínky použití
  3. Testování
  4. Autentizace
    1. Pomocí session
    2. Přímým předáním parametrů
  5. Registrace
  6. Statistiky
  7. Práce s kolekcí
  8. Práce s katalogem
  9. Datové formáty
  10. Datové typy
    1. bool
    2. date
  11. Kategorie CWG
  12. Chybové kódy
  13. Seznam změn

Úvod

CWG API slouží k práci s CWG kolekcí z aplikací třetích stran. Základem API je adresa http://cwg.gcm.cz/api/, která je kořenovým adresářem pro volání všech API funkcí.

Komunikace s API je možná jak přes metodu GET, tak přes metodu POST, kdy POST je doporučována pro produkční použití. Každá funkce API, která očekává nějaké parametry, je má dokumentovány a očekává je právě předané metodou POST nebo GET. Každá funkce je identifikována její jedinečnou URL adresou.

Návratové údaje z API mohou být buďto ve formě XML nebo JSON, případně přímo data, je-li výstupem akce soubor. Formát výstupních dat je specifikován parametrem format, který může nabývat buď hodnoty "json" pro JSON výstup, nebo hodnoty "xml" pro XML výstup. Hodnota parametru rozlišuje velká a malá písmena. Pokud je návratem z funkce soubor, na hodnotu tohoto parametru nebude brán zřetel. Výchozí formát výstupu, pokud parametr není uveden, je JSON.

Podmínky použití

API je zdarma k dispozici pro kohokoliv, včetně této dokumentace. Přístup k API však berte jako privilegium, nikoliv právo. V případě nadměrného přetěžování nebo zneužívání může dojít k ukončení provozu nebo zablokování příslušných funkcí.

Testování

Pro testování systému se doporučuje používat testovací instanci serveru, přístupnou na adrese http://test.cwg.gcm.cz/api/. Tato instance běží na kopii databáze a jakékoliv změny v ní provedené se nepromítnou do skutečné databáze na serveru http://cwg.gcm.cz/.

Testovací databáze je každý den v noci zahozena a nahrazena kopií databáze ze skutečného serveru, takže vždy obsahuje více méně aktuální data a změny provedené v testovací databázi budou nejpozději následující noc zapomenuty.

Testovací server je jinak identickou kopií serveru skutečného, jen pracuje s jinými daty, takže vše co funguje v testovací verzi by mělo identicky fungovat ve skutečné verzi.

Autentizace

Většina funkcí vyžaduje ke své funkčnosti autentizaci. Tu je možno provést dvěma způsoby.

Pomocí session

První možností je inicializace session a násedné předání session identifikátoru při dalších voláních API. Jedná se o doporučovaný způsob komunikace, pokud je očekáváno větší množství volání API. Uživatelské jméno a heslo pak také prochází po síti pouze jednou.

Všem dalším funkcím vyžadujícím autentizaci se poté předává parametr session, který obsahuje řetězec vrácený funkcí /login.

/login

Parametry

username
string
Uživatelské jméno
password
string
Heslo

Návratová struktura

Success
boolean
Úspěch akce. true v případě úspěšného ověření, false v případě chyby.
Error
string
V případě neúspěchu obsahuje chybovou zprávu s popisem chyby.
ErrorCode
int
Chybový kód.
Session
string
V případě úspěchu obsahuje 32 znaků dlouhý identifikátor session, který aplikace musí uchovat a používat v dalším volání funkcí. Platnost identifikátoru je 1 hodina od posledního volání API.

Popis

Slouží k autentizaci uživatele. Předané parametry identifikují uživatele a v případě úspěšného ověření je zpět vrácen identifikátor session, který je možné použít k dalšímu volání API.

/login-info

Parametry

Funkce nepřijímá žádné specifické parametry kromě autentizačních.

Návratová struktura

Success
string
Úspěch akce. true v případě že je uživatel přihlášen, false pokud přihlášen není.
Error
string
V případě neúspěchu obsahuje chybovou zprávu s popisem chyby (důvodem, proč uživatel není přihlášen).
ErrorCode
int
Chybový kód.
User
struct
Informace o přihlášeném uživateli.
name
string
Uživatelské jméno

Přímým předáním parametrů

Druhou možností, primárně určenou pro ojedinělé volání API, je předání přihlašovacích údajů přímo mezi parametry volané funkce. Parametry jsou stejné jako při volání funkce /login, návratová struktura obsahuje v případě neúspěchu to samé co při volání funkce /login, v případě úspěchu se však nepředává identifikátor session, ale dojde k vykonání požadované funkce a návratová data se liší podle volané funkce.

Registrace

Pomocí API je také možné založit nový uživatelský účet.

/register

Parametry

username
string
Uživatelské jméno. Smí obsahovat jakékoliv znaky a musí být v systému unikátní.
password
string
Heslo. Heslo je posíláno jako čistý text a musí být nejméně 6 znaků dlouhé.
email
string
Email

Návratová struktura

Success
bool
Úspěch akce. true v případě úspěšné registrace, false v případě chyby.
Error
string
Chybová zpráva v případě, že došlo k chybě ve zpracování registrace.
ErrorCode
int
Chybový kód.
User
struct
Informace o zaregistrovaném uživateli.
name
string
Uživatelské jméno

Popis

Tato funkce nevyžaduje autentizaci.

Slouží k registraci nového uživatelského účtu. Funkčnost je ekvivalentní registraci na webu, včetně požadavků na vstupní parametry. Všechny tři parametry (uživatelské jméno, heslo a email) jsou povinné.

Statistiky

/users/statbar/<username>

Parametry

username
string
Parametr se předává přímo jako součást volání funkce. Obsahuje jméno uživatele, jehož statistiky chceme získat.

Návratová struktura

Success
boolean
Úspěch akce.
User
string
Uživatelské jméno, jehož statistiky jsou vráceny. Odpovídá parametru username.
UniqueCWGCount
int
Počet unikátních CWG, která má uživatel ve své sbírce.

Popis

Tato funkce nevyžaduje autentizaci.

Funkce vrací počet unikátních CWG, které jsou ve sbírce. Tento údaj může být použit k zobrazování například ve statistikách nebo na ikonkách.

Práce s kolekcí

/collection/export

Parametry

format
enum
Formát exportu kolekce. O konkrétních formátech více v kapitole Datové formáty
Přípustné hodnoty:
since
datetime
null
Volitelný parametr. Pokud je specifikován, zahrne do exportu pouze změny od specifikovaného data.
from
int
0
Pouze pro JSON export. Stránkování - počet záznamů, které mají být přeskočeny. Export je řazen podle data poslední aktualizace záznamu.
count
int
100
Pouze pro JSON export. Stránkování - kolik záznamů se má maximálně exportovat. Hodnota může být v rozmezí (1-1000). Export je řazen podle data poslední aktualizace záznamu.

Návratová hodnota

Funkce vrací soubor s exporem kolekce ve formátu závislém na specifikovaném parametru.

Popis

Funkce slouží pro export informací o katalogizovaných CWG pro přihlášeného uživatele.

/collection/collect

Parametry

cwgno
string
Katalogové číslo CWG, které má být zařazeno do kolekce.
name
string
Název CWG v případě, že se jedná o nekatalogizované CWG.
version
int
Verze CWG v případě, že se jedná o nekatalogizované CWG.
date
date
aktuální datum
Volitelný parametr. Datum zařazení do kolekce.
year
int
aktuální rok
Volitelný parametr. Rok výroby CWG.
pieces
int
?
Volitelný parametr. Počet zařazených kusů.
comment
string
""
Volitelný parametr. Poznámka týkající se katalogizovaného kusu CWG.
update
boolean
true
V případě, že je CWG již v kolekci s uvedeným datem, má dojít k aktualizaci nebo nahrazení záznamu? true pro aktualizaci (doplnění dalšího kusu), false pro nahrazení.

Návratová struktura

Success
boolean
Úspěch akce. true CWG bylo úspěšně zařazeno do kolekce.
Error
string
V případě neúspěchu obsahuje chybovou zprávu.
ErrorCode
int
Chybový kód.

Popis

Slouží k zařazení nového kusu CWG do kolekce. K identifikaci CWG slouží jeho katalogové číslo, případně pokud CWG není zařazeno v oficiálním katalogu, slouží k identifikaci název a verze CWG. Pokud se jedná o katalogizované CWG, nemusí být parametry name a version přítomny, stejně tak pokud se jedná o nekatalogizované CWG, nemusí být přítomen parametr cwgno.

Parametry date, pieces, comment jsou volitelné a slouží k doplění podrobnějších informací ke katalogizovanému kusu CWG. Pro jednoduché zařazení do kolekce (ekvivalentní kliknutí na zelenou fajvku v katalogu) stačí pouze zavolat tuto funkci s identifikací CWG.

Pro vyřazení CWG z kolekce uveďte parametr pieces = 0, update = false.

/collection/import

Parametry

overwrite
boolean
false
Uvádí, jestli má dojít k přepisu údajů v kolekci, nebo k jejich aktualizaci. false = aktualizovat, true = přepsat
fileformat
enum
Formát importovaného souboru. O formátech více v kapitole Datové formáty.
Přípustné hodnoty:

Návratová struktura

Success
bool
Úspěch akce.
Error
string
V případě neúspěchu obsahuje popis chyby.
ErrorCode
int
Chybový kód.
ImportedStatus
struct
Informace o výsledcích importu
added
int
Počet nově zařazených CWG.
updated
int
Počet aktualizovaných CWG.
errors
array[struct]
Pole obsahující údaje o chybách při importu.
cwg_no
string
Katalogové číslo CWG, pokud je uvedeno
name
name
Název CWG, pokud je uveden.
version
version
Verze CWG, pokud je uvedena.
error
string
Popis chyby.

Popis

Import kolekce. Standardní chování pouze doplní informace o nově zařazených CWG, pokud v importovaném souboru pro některý ze záznamů neexistuje informace, nedojde k jeho smazání.

Při hodnotě parametru overwrite = true dojde ke kompletnímu přepisu kolekce, tj. CWG která nejsou v importovaném souboru uvedena, budou vymazána z uživatelovy kolekce.

Uživatel by měl VŽDY být varován nebo dostat na výběr v případě použití parametru overwrite = true.

Práce s katalogem

/cwg/info

Parametry

cwgno
string
Katalogové číslo CWG, které má být zařazeno do kolekce.
name
string
Název CWG v případě, že se jedná o nekatalogizované CWG.
version
int
Verze CWG v případě, že se jedná o nekatalogizované CWG.

Návratová struktura

Success
bool
Úspěch akce
Error
string
V případě neúspěchu obsahuje chybovou zprávu.
ErrorCode
int
Chybový kód.
CWG
struct
Informace o CWG.
cwgno
string
Katalogové číslo CWG.
name
string
Název CWG
version
int
Verze CWG
category
int
ID kategorie ve které je CWG zařazeno. Seznam dostupných ID viz kapitola Kategorie CWG.
comment
string
Poznámka uvedená v katalogu
image
string
Adresa obrázku CWG.
profile
string
Adresa profilu na gc.com.
since
date
Datum zařazení do katalogu.
collection
array[struct]
Seznam uživatelů mající toto CWG ve své kolekci.
name
string
Uživatelské jméno
profile
string
Adresa veřejného profilu uživatele
pieces
int
Počet kusů, které má uživatel ve sbírce
appropox
bool
Pokud je hodnota true, není počet kusů přesný - uživatel má u některého z CWG uveden pouze příznak že ho má v kolekci, avšak bez specifikování počtu kusů.
offers
array[struct]
Seznam uživatelů nabízejících toto CWG.
name
string
Uživatelské jméno
profile
string
Adresa veřejnéno profilu uživatele.
pieces
int
Počet kusů, které uživatel nabízí.
comment
string
Počet kusů, které uživatel nabízí.
wants
array[struct]
Seznam uživatelů, kteří toto CWG shánějí.
name
string
Uživatelské jméno
profile
string
Adresa veřejného profilu uživatele.
notwant
array[struct]
Seznam uživatelů, kteří toto CWG nechtějí.
name
string
Uživatelské jméno
profile
string
Adresa veřejného profilu uživatele.

Popis

Informace o jednom CWG. Specifikovat CWG je možno jeho katalogovým číslem nebo kombinací název + verze pro nekatalogizovaná CWG.

Obsahuje informace dostupné ve stejné podobě jako jsou obsaženy v katalogu na webu + informace o tom, kteří uživatelé CWG nabízejí, shání, nechtějí a mají v kolekci.

/cwg/export

Parametry

since
datetime
null
Volitelný parametr. Pokud je specifikován, budou exportovány pouze změněné záznamy od specifikovaného data. Změna může být jak ze strany katalogu (aktualizace údajů o CWG), tak ze strany uživatele (změna některého ze stavů, které jsou v tomto exportu obsaženy).

Návratová hodnota

Funkce vrací soubor s exporem kolekce ve formátu CSV. CSV obsahuje následující sloupečky:

  1. Katalogové číslo
  2. Název
  3. Verze
  4. ID Kategorie (viz číselník kategorií)
  5. Komentář
  6. Adresa obrázku
  7. Adresa profilu
  8. Datum zařazení do katalogu (ISO 8601)
  9. Má v kolekci? (true/false)
  10. Nabízí? (true/false)
  11. Shání? (true/false)
  12. Nechce? (true/false)
  13. Datum poslední aktualizace stavu CWG ze strany uživatele (nebo null pokud uživatel u CWG nic nemá)
  14. Unikátní ID CWG

Jako oddělovač je použita čárka a pokud některý ze sloupečků obsahuje tento znak, je celá hodnota sloupečku uvedena v uvozovkách (").

V HTTP hlavičce Item-Count je zároveň odeslán celkový počet položek v exportním souboru.

Popis

Export celého CWG katalogu včetně základních informací o uživatelově sbírce.

/cwg/search

Parametry

name
string
Název CWG, který se má vyhledat.

Návratová hodnota

Funkce vrací soubor s výsledky vyhledávání kolekce ve formátu CSV. CSV obsahuje následující sloupečky:

  1. Katalogové číslo
  2. Název
  3. Verze
  4. ID Kategorie (viz číselník kategorií)
  5. Komentář
  6. Adresa obrázku
  7. Adresa profilu
  8. Datum zařazení do katalogu (ISO 8601)
  9. Má v kolekci? (true/false)
  10. Nabízí? (true/false)
  11. Shání? (true/false)
  12. Nechce? (true/false)
  13. Datum poslední aktualizace stavu CWG ze strany uživatele (nebo null pokud uživatel u CWG nic nemá)
  14. Unikátní ID CWG

Jako oddělovač je použita čárka a pokud některý ze sloupečků obsahuje tento znak, je celá hodnota sloupečku uvedena v uvozovkách (").

Popis

Export celého CWG katalogu včetně základních informací o uživatelově sbírce.

/cwg/categoryList

Parametry

Funkce nepřijímá žádné specifické parametry kromě autentizačních.

Návratová struktura

Success
bool
Úspěch akce
Error
string
V případě neúspěchu obsahuje chybovou zprávu.
ErrorCode
int
Chybový kód.
Categories
array
Seznam existujících kategorií
id
int
Kód kategorie
name
string
Název kategorie
freeAdd
bool
Pokud je true, do této kategorie je možné vkládat nová CWG.
parentId
int
ID nadřazené kategorie nebo null, pokud se jedná o kategorii na nejvyšší úrovni.

Popis

Funkce vrací seznam existujících a platných kategorií v systému.

/cwg/joinedList

Parametry

since
datetime
null
Volitelný parametr - čas poslední aktualizace. Ve výsledku budou zahrnuty jen sloučené CWG, které byly sloučeny později než je hodnota parametru.

Návratová hodnota

Success
bool
Úspěch akce
Error
string
V případě neúspěchu obsahuje chybovou zprávu.
ErrorCode
int
Chybový kód.
Joined
array
Seznam sloučených CWG
from_cwg
int
ID CWG, které bylo zrušeno sloučením.
to_cwg
int
ID cílového CWG, které zůstalo v katalogu po sloučení.

/cwg/images

Parametry

since
datetime
null
Volitelný parametr. Pokud je specifikován, pošle pouze obrázky, které jsou nové nebo aktualizované od zadaného data. Slouží k inkrementální aktualizaci lokálního úložiště obrázků CWG. Bez tohoto parametru je vždy staženo všechno, což je časově i datově náročná operace, takže doporučuji používat inkrementální režim.

Návratová hodnota

Funkce vrací soubor ve formátu ZIP s požadovanými obrázky.

Popis

Funkce sloužící ke stažení obrázků (náhledů) CWG. Umí pracovat ve dvou módech - plný a inkrementální. V případě, že není předán parametr since, jedná se o plný mód. Pokud parametr předán je, jedná se o inkrementální.

Při plném módu jsou vždy odeslány všechny obrázky, které existují.

Při inkrementálním módu jsou odeslány pouze obrázky, které byly aktualizovány nebo přidány od specifikovaného data.

Z důvodu velké datové náročnosti doporučuji vždy, pokud je to možné, využívat inkrementální mód, který zbytečně nestahuje již stažená data.

Datové formáty

V této kapitole jsou popsané datové formáty pro výměnu dat mezi CWG kolekcí a externí aplikací v momentě, kdy není možné použít běžné rozhraní JSON/XML a je potřeba pracovat se soubory.

Kompletní XML

Formát obsahující veškeré informace o CWG včetně všech informací o uživatelských příznacích - kolekce, shání/nechce, nabízí.

Jedná se o XML soubor popsaný schématem cwgexport.xsd. Tento formát se bude nadále rozšiřovat o další údaje v případě aktualizace systému, avšak vždy se zachováním zpětné kompatibility. Aktuální schéma je vždy umístěno na uvedené adrese.

JSON

Exportní formát pro snazší práci s kolekcí v aplikacích, které lépe pracují s formátem JSON než XML. Struktura vrácených dat je následující:

Success
bool
Úspěch exportu.
Export
array of struct
Samotná data exportu
id
int
Interní identifikátor CWG.
cwgno
string
Katalogové číslo CWG. V exportu chybí, pokud CWG není zařazeno v oficiálním katalogu.
name
string
Název CWG.
category
struct
Kategorie CWG
id
int
ID kategorie
name
string
Název kategorie
version
int
Verze CWG
image
string
Adresa obrázku
collection
array | bool
Pokud je pole typu bool (true/false), udává, jestli má uživatel CWG ve své kolekci. Pokud se jedná o strukturu, uživatel CWG v kolekci zcela jistě má a navíc jsou o jeho sbírce k dispozici podrobnější informace. Jednotlivé oložky pole poté obsahují následující strukturu záznamu:
date
date
Datum zařazení do kolekce
year
int
Ročník CWG
comment
string
Komentář
pieces
int
Počet kusů v kolekci.
wants
bool
Indikuje, zdali uživatel toto CWG chce.
notwant
bool
Indikuje, zdali uživatel toto CWG nechce.
offers
struct | bool
Indikuje, zdali uživatel toto CWG nabízí. Může být buď true/false, nebo, pokud jsou k dispozici podrobnější informace, struktura následujícího formátu:
pieces
int
Počet kusů, které uživatel nabízí
comment
string
Komentář uživatele k jeho nabídce.
TotalCount
int
Celkový počet záznamů které je možné exportovat
From
int
Offset exportu (počet vynechaných záznamů od začátku)
Count
int
Počet požadovaných záznamů. Toto číslo je pouze to, které bylo volitelně specifikováno v parametru nebo jeho výchozí hodnota. Skutečný počet záznamů se může lišit v závislosti na jejich skutečné existenci.

Datové typy

Tato kapitola obsahuje popis datových typů, které jsou používány v API.

bool

Hodnota typu ano/ne, pravda/nepravda. Výstupní hodnota je vždy true nebo false, vstupní hodnota je přijímána buď jako true/false nebo 1/0.

date

Datum ve formátu YYYY-MM-DD (ISO 8601).

datetime

Datum a čas ve formátu YYYY-MM-DDTHH:MM:SS (ISO 8601).

Kategorie CWG

CWG jsou řazena do kategorií. Každá kategorie má svůj kód podle následující tabulky. Kategorie se mohou v budoucnu rozrůstat.

Kód Název Poznámka
1 Osobní CWG
2 Eventová CWG Zrušeno, nepoužívá se.
3 Speciální CWG
4 Extra osobní CWG
5 SWG
6 Limited edition SWG
7 Extra osobní SWG

Zahraniční

Kód Název Poznámka
8 Dutch Holandská
9 German Německá
14 Polish Polská
16 Australian Australská
17 Finish Finská
18 Hungarian Maďarská
19 French Francouzská
20 Danish Dánská

Ostatní

Kód Název Popis
13 MWG Micro Wood Geocoin

Chybové kódy

Každý chybový stav, který API rozeznává, je opatřen chybovým kódem, díky kterému je možné rozlišit jaká chyba nastala.

Chyby autentizace

Kód Popis chyby
101 Zadané přihlašovací údaje jsou chybné.
102 Přístup byl odepřen (z důvodu nedostatečných oprávnění).
103 Uživatel není přihlášen (session vypršela).

Chyby vstupních parametrů

Kód Popis chyby
200 Chybné vstupní parametry
201 Chybějící přihlašovací parametry.
202 Chybějící identifikace CWG (cwgno nebo název+verze).
203 Chybný formát.
204 Nebyl přiložen soubor.
205 Zadané heslo je příliš krátké.

Kód Popis chyby
401 Na dotaz bylo nalezeno více výsledků než bylo očekáváno. Je třeba dotaz upřesnit.
402 Při registraci bylo zadáno již existující uživatelské jméno.
404 Hledaná položka nebyla nalezena.

Chyby serveru

Kód Popis chyby
500 Chyba serveru.
501 Import nepracuje správně.
502 Import selhal.
503 Neznámá metoda.

Seznam změn

v1.3.0 - 26.12.2013

v1.2.1 - 16.8.2013