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. This is similar to the way current Query API returns status codes.
 * Zahrnuje informace o chybě do správné odpovědi

Pros: HTTP error codes are used only for the networking issues, not for the data (logical errors). We do not tied to the existing HTTP error codes.

Cons: If the data format parameter is not properly specified, what is the format of the output data? Application has to parse the object to know of an error (perf?). Error checking code will have to be on both the connection and data parsing levels.