API:Etiketa
 | Tato stránka je součástí dokumentace k API Action MediaWiki. |
 | Tato stránka ve zkratce:
|
Tato stránka obsahuje osvědčené postupy, které je třeba dodržovat při používání rozhraní API.
Chování
Limit požadavku
Neexistuje žádný pevný rychlostní limit pro požadavky na čtení, ale buďte ohleduplní a snažte se web nezrušit. Většina systémových administrátorů si vyhrazuje právo vás bez okolků zablokovat, pokud ohrozíte stabilitu jejich stránek.
Vytváření požadavků v sérii, nikoli paralelně, čekáním na dokončení jednoho požadavku před odesláním nového požadavku, by mělo vést k bezpečnému počtu požadavků. Také se doporučuje, abyste požádali o více položek v jedné žádosti:
- Kdykoli je to možné, použijte svislítko (
|), např.titles=PageA|PageB|PageC, místo toho, abyste pro každý titul zadali novou žádost. - Použití generátoru místo požadavku na každý výsledek z jiného požadavku.
- Použijte kompresi GZip při volání API nastavením
Accept-Encoding: gzippro snížení využití šířky pásma.
Požadavky, které provádějí úpravy, mění stav nebo jinak, nejsou požadavky pouze pro čtení a podléhají omezení rychlosti. Přesný limit sazby může záviset na typu akce, vašich uživatelských právech a konfiguraci webové stránky, na kterou zadáváte požadavek. Limity, které se na vás vztahují, lze určit přístupem ke koncovému bodu API action=query&meta=userinfo&uiprop=ratelimits.
Když dosáhnete limitu počtu požadavků, obdržíte chybovou odpověď API s kódem chyby ratelimited. Když narazíte na tuto chybu, můžete požadavek opakovat, měli byste však prodloužit dobu mezi následujícími požadavky. Běžnou strategií je Exponenciální ústup.
Analýza revizí
I když je možné dotazovat se na výsledky z konkrétního čísla revize pomocí parametru revid, je to pro servery nákladná operace.
Chcete-li získat konkrétní revizi, použijte parametr oldid. Například:
Parametr maxlag
Pokud vaše úloha není interaktivní, tj. uživatel nečeká na výsledek, měli byste použít parametr maxlag.
Hodnota parametru maxlag by měla být celé číslo v sekundách.
Například:
Tím zabráníte spuštění úlohy, když je zatížení serverů vysoké.
Vyšší hodnoty znamenají agresivnější chování, nižší hodnoty jsou hezčí.
Další podrobnosti najdete na stránce Manual:Maxlag parameter.
Záhlaví User-Agent
Nejlepší je nastavit popisné záhlaví User Agent.
K tomu použijte User-Agent: clientname/version (kontaktní informace, např. uživatelské jméno, email) framework/version....
Například v PHP:
ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) UsedBaseLibrary/1.4');
Nekopírujte jednoduše user-agent oblíbeného webového prohlížeče. To zajišťuje, že pokud se problém objeví, je snadné vysledovat, kde vznikl.
Pokud voláte API z JavaScriptu založeného na prohlížeči, možná nebudete moci ovlivnit hlavičku User-Agent, v závislosti na prohlížeči.
Chcete-li to obejít, použijte hlavičku Api-User-Agent.
Další podrobnosti naleznete v m:User-Agent_policy.
Formáty dat
Všichni noví uživatelé rozhraní API by měli používat JSON. Další podrobnosti viz API:Data_formats.
Výkon
Hromadné stahování dat není pomocí Action API vždy extrémně efektivní. Na wikinách Wikimedie existují rychlejší způsoby, jak získat data hromadně, viz m:Research:Data a wikitech:Portal:Data Services pro více podrobností.
Další poznámky
Pokud vaše požadavky získají data, která lze na chvíli uložit do mezipaměti, měli byste podniknout kroky k jejich uložení do mezipaměti, abyste nepožadovali stejná data znovu a znovu. Někteří klienti mohou být schopni ukládat data do mezipaměti sami, ale u jiných (zejména klientů JavaScriptu) to není možné.
Kdykoli čtete data z rozhraní API webové služby, měli byste se pokusit, pokud je to možné, použít požadavky GET, nikoli POST, protože ty nelze uložit do mezipaměti.
Související odkazy
- API:Hlavní stránka - průvodce rychlým startem.
- Spravováno MediaWiki Interfaces Team.
- Živý chat (IRC): #mediawiki-core připojit se
- Nástroj pro sledování problémů: Phabricator MediaWiki-Action-API (nahlášení problému)