API:Etiketa

Tato stránka obsahuje osvědčené postupy, které je třeba dodržovat při používání rozhraní API.

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: gzip pro 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.

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:

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 .

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.

Všichni noví uživatelé rozhraní API by měli používat JSON . Další podrobnosti viz API:Datové formáty .

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 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é.

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.

API požadavky na wikiny Wikimedie musí obsahovat smysluplnou hlavičku User-Agent. Další podrobnosti naleznete v m:User-Agent_policy.

Kromě limitu rychlosti založeného na akcích uživatelů podléhají požadavky API na wiki Wikimedie limitu rychlosti API .

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í.

• 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

• 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)

• MediaWiki action API/cs