API:Implementation Strategy/cs

Vysvětluje implementaci MediaWiki API v jádru. Pokud chcete ve svém kódu poskytnout rozhraní API pro klienty k použití, přečtěte si.



Struktura souboru/modulu

 * je vstupní bod umístěný v kořenovém adresáři wiki. Viz API:Hlavní stránka#Koncový bod.
 * bude obsahovat všechny soubory související s API, ale žádný z nich nebude povolen jako vstupní bod.
 * Všechny třídy API jsou odvozeny od společné abstraktní třídy . Základní třída poskytuje běžné funkce, jako je analýza parametrů, profilování a zpracování chyb.
 * je hlavní třída vytvořená pomocí . Určuje, který modul se má spustit, na základě parametru  .   také vytvoří instanci třídy , která obsahuje pole výstupních dat a související pomocné funkce. Nakonec   vytvoří instanci formátovací třídy, která klientovi vyvede data z   ve formátu XML/JSON/PHP nebo v jiném formátu.
 * Jakýkoli modul odvozený z  obdrží během vytváření instance odkaz na instanci , takže během provádění může modul získat sdílené prostředky, jako je výsledný objekt.



Moduly dotazů

 * se chová podobně jako  v tom, že spouští submoduly. Každý submodul je odvozen od   (kromě samotného , což je modul nejvyšší úrovně). Během vytváření instance obdrží submoduly odkaz na instanci ApiQuery.
 * Všechny moduly dotazů rozšíření by měly používat 3 nebo více písmenných předpon. Základní moduly používají 2 písmenné předpony.
 * Realizační plán :
 * Získejte sdílené parametry dotazu  k určení potřebných submodulů.
 * Vytvořte objekt  a naplňte jej z parametrů  . Objekt   obsahuje seznam stránek nebo revizí, se kterými budou moduly dotazů pracovat.
 * Na požádání se spustí modul generátoru k vytvoření dalšího . Podobné jako piping streams v UNIXu. Dané stránky jsou vstupem do generátoru, který vytváří další sadu stránek pro všechny ostatní moduly, na kterých mohou pracovat.
 * Požadavky na pokračování dotazu:
 * SQL dotaz musí být zcela uspořádaný. Jinými slovy, dotaz musí používat všechny sloupce nějakého jedinečného klíče buď jako konstanty v klauzuli  nebo v klauzuli.
 * V MySQL se jedná o exclusive or až do bodu, kdy se dotazování Foo a Bar musí řadit podle názvu, ale nikoli jmenného prostoru (jmenný prostor je konstantní 0), Foo a Talk:Foo se musí řadit podle jmenného prostoru, ale ne podle názvu (název je konstantní "Foo") a Foo a Talk:Bar se musí řadit podle jmenného prostoru i názvu.
 * SQL dotaz nesmí řadit soubory.
 * Hodnota přidělená  musí zahrnovat všechny sloupce v klauzuli.
 * Při pokračování by měla být do klauzule  přidána jedna složená podmínka. Pokud má dotaz , měla by tato podmínka vypadat nějak takto:

(column_0 > value_0 OR (column_0 = value_0 AND&#xa; (column_1 > value_1 OR (column_1 = value_1 AND&#xa; (column_2 >= value_2)&#xa; ))&#xa;))

Samozřejmě, vyměňte ">" za "<", pokud vaše sloupce  používají. Ujistěte se, že se v hodnotách vyhnete vkládání SQL.



Vnitřní datové struktury

 * Query API má velmi úspěšnou strukturu jedné globální vnořené struktury . Různé moduly by přidávaly kusy dat do mnoha různých bodů tohoto pole, až by je nakonec pro klienta vykreslila jedna z tiskáren (výstupní moduly). Pro rozhraní API doporučujeme zabalit toto pole jako třídu s pomocnými funkcemi pro připojení jednotlivých listových uzlů.



Hlášení chyb/stavu
Prozatím jsme se rozhodli zahrnout informace o chybě do stejného strukturovaného výstupu jako normální výsledek (možnost #2).

Ve výsledku můžeme buď použít standardní chybové kódy HTTP nebo vždy vrátit správně naformátovaná data:

void header( string reason_phrase [, bool replace [, int http_response_code]] ) lze použít k nastavení návratového stavu operace. Můžeme definovat všechny možné hodnoty, takže za neúspěšné přihlášení můžeme vrátit   a  , zatímco v případě úspěchu bychom jednoduše vrátili odpověď beze změny hlavičky.
 * Pomocí HTTP kódu

Výhody: Je to standard. Klient se vždy musí vypořádat s chybami HTTP, takže použití kódu HTTP pro výsledek by odstranilo jakékoli samostatné zpracování chyb, které by klient musel provést. Vzhledem k tomu, že klient může požadovat data ve více formátech, neplatný parametr formátu by byl stále správně zpracován, protože by to byl jednoduše další kód chyby http.

Nevýhody: ...

Tato metoda by vždy vrátila správně formátovaný objekt odpovědi, ale chybový stav/popis budou jediné hodnoty uvnitř tohoto objektu. Je to podobné způsobu, jakým aktuální Query API vrací stavové kódy.
 * Zahrnuje informace o chybě do správné odpovědi

Výhody: Chybové kódy HTTP se používají pouze pro problémy se sítí, nikoli pro data (logické chyby). Nejsme vázáni na stávající kódy chyb HTTP.

Nevýhody: Pokud parametr formátu dat není správně zadán, jaký je formát výstupních dat? Aplikace musí objekt analyzovat, aby věděla o chybě (výkon?). Kód kontroly chyb bude muset být na úrovni připojení i analýzy dat.

