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.
Pokud narazíte na tuto chybu, můžete daný požadavek zopakovat, měli byste však prodloužit dobu mezi jednotlivými požadavky.
Běžnou strategií pro toto je Exponenciální odstup.
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 Příručka:Parametr Maxlag.
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.
Formáty dat
Všichni noví uživatelé rozhraní API by měli používat JSON. Další podrobnosti viz API:Datové formáty.
Ukládání do mezipaměti
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é.
Požadavek POST
Kdykoli čtete data z rozhraní API webové služby, měli byste se pokusit použít požadavky GET, pokud je to možné, nikoli POST, protože druhý nelze uložit do mezipaměti a v konfiguracích multi-datacenter (včetně stránek Wikimedie) může jít do vzdálenějšího datového centra.
Ve výjimečných případech, kdy opravdu potřebujete použít POST pro požadavek na čtení, jako je volání action=parse s dlouhým řetězcem wikitextu, zvažte nastavení hlavičky Promise-Non-Write-API-Action: true.
To pomáhá zajistit, aby byl váš požadavek POST zpracován aplikačním serverem v nejbližším datovém centru, je-li to vhodné.
Pokyny pro wikiny Wikimedie
Kromě výše popsaných osvědčených postupů platí pro používání Action API pro přístup k wikinám Wikimedie následující pokyny. Viz také oficiální pokyny pro použití API na wiki Wikimedia Foundation Governance.
Pravidla User-Agent
API požadavky na wikiny Wikimedie musí obsahovat smysluplnou hlavičku User-Agent. Další podrobnosti naleznete v m:User-Agent_policy.
Limity rychlosti
Kromě limitu rychlosti založeného na akcích uživatelů podléhají požadavky API na wiki Wikimedie limitu rychlosti API.
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í.
Související odkazy
- Oficiální pokyny pro používání API na Wikimedia Foundation Governance wiki
- Zásady pro roboty Wikimedie na Wikitech
- API:Main page - průvodce rychlým startem.
- Manual:Rate limits & Wikimedia APIs/Rate limits
Správce kódu
- 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)