API:Rozšíření
Tato stránka je součástí dokumentace k API Action MediaWiki. |
Tento dokument popisuje vytvoření modulu API v rozšíření pro použití s MediaWiki 1.30 a novějšími.
Vytvoření a registrace modulu
Všechny moduly API jsou podtřídy ApiBase , ale některé typy modulů používají odvozenou základní třídu. Způsob registrace závisí také na typu modulu.
- akční moduly
- Moduly, které poskytují hodnotu pro hlavní parametr
action
, by měly podtřídu ApiBase . Měli by být registrováni vextension.json
pomocí klíčeAPIModules
. - moduly formátů
- Moduly, které poskytují hodnotu pro hlavní parametr
format
, by měly mít podtřídu ApiFormatBase. Měly by být registrovány vextension.json
pomocí klíčeAPIFormatModules
. Je velmi neobvyklé, že rozšíření potřebuje přidat modul formátu. - dotazovací podmoduly
- Moduly, které poskytují hodnotu pro parametry
prop
,list
nebometa
ažaction=query
, by měly podtřídu ApiQueryBase (pokud nejsou použitelné jako generátor) nebo ApiQueryGeneratorBase (pokud jsou použitelné jako generátor). Měly by být registrovány vextension.json
pomocí klíčeAPIPropModules
,APIListModules
neboAPIMetaModules
.
Ve všech případech je hodnotou registračního klíče objekt s názvem modulu (tj. hodnotou parametru) jako klíčem a názvem třídy jako hodnotou. Moduly lze také registrovat podmíněně pomocí háčků ApiMain::moduleManager (pro moduly akcí a formátů) a ApiQuery::moduleManager (pro podmoduly dotazů).
Zavádění
Předpona
V konstruktoru vašeho modulu API můžete při volání parent::__construct()
zadat volitelnou předponu pro parametry vašeho modulu.
(Ve vygenerované dokumentaci modulu je tato předpona, pokud existuje, uvedena v závorkách v záhlaví modulu.)
Pokud je váš modul podmodulem dotazu, je vyžadována předpona, protože klient může vyvolat více podmodulů, z nichž každý má své vlastní parametry v jednom požadavku.
U modulů akcí a formátů je předpona volitelná.
Parametry
Většina modulů vyžaduje parametry.
Ty jsou definovány implementací getAllowedParams().
Vrácená hodnota je asociativní pole, kde klíče jsou (bez předpony) názvy parametrů a hodnoty jsou buď skalární výchozí hodnota parametru, nebo pole definující vlastnosti parametru pomocí konstant PARAM_*
definovaných pomocí ApiBase.
Příklad ilustruje syntaxi a některé běžnější konstanty PARAM_*
.
protected function getAllowedParams() {
return [
// Volitelný parametr s výchozí hodnotou
'simple' => 'value',
// Povinný parametr
'required' => [
ApiBase::PARAM_TYPE => 'string',
ApiBase::PARAM_REQUIRED => true,
],
// Parametr přijímající více hodnot ze seznamu
'variable' => [
// Výchozí sada hodnot
ApiBase::PARAM_DFLT => 'foo|bar|baz',
// Všechny možné hodnoty
ApiBase::PARAM_TYPE => [ 'foo', 'bar', 'baz', 'quux', 'fred', 'blah' ],
// Označte, že je akceptováno více hodnot
ApiBase::PARAM_ISMULTI => true,
// Použijte standardní dokumentační zprávy "pro hodnotu".
ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
],
// Standardní "limitní" parametr. Obecně je nejlepší se od tohoto standardu nelišit.
'limit' => [
ApiBase::PARAM_DFLT => 10,
ApiBase::PARAM_TYPE => 'limit',
ApiBase::PARAM_MIN => 1,
ApiBase::PARAM_MAX => ApiBase::LIMIT_BIG1,
ApiBase::PARAM_MAX2 => ApiBase::LIMIT_BIG2,
],
];
}
Parametry jsou dokumentovány pomocí mechanismu MediaWiki i18n. Podrobnosti viz #Dokumentace.
Provedení a výstup
Kód ve skutečnosti implementující modul jde metodou execute(). Tento kód bude obecně používat $this→extractRequestParams() k získání vstupních parametrů a použije $this→getResult() k získání objektu ApiResult, do kterého lze přidat jakýkoli výstup.
Podmoduly Query prop by měly používat $this→getPageSet() pro přístup k sadě stránek, na kterých se má pracovat.
Podmoduly dotazů, které lze použít jako generátory, budou také muset implementovat executeGenerator(), který je předán, a ApiPageSet, který by měl být vyplněn vygenerovanými stránkami.
V tomto případě by ApiResult
neměl být obecně použit.
Ukládání do mezipaměti
Ve výchozím nastavení jsou odpovědi API označeny jako neuložitelné do mezipaměti ('Cache-Control: private')!
U akčních modulů můžete povolit ukládání do mezipaměti voláním $this→getMain()→setCacheMode().
To stále vyžaduje, aby klienti předali parametry maxage
nebo smaxage
, aby skutečně umožnili ukládání do mezipaměti.
Ukládání do mezipaměti můžete vynutit také voláním $this→getMain()→setCacheMaxAge().
U modulů dotazů nevolat tyto metody. Ukládání do mezipaměti můžete povolit implementací getCacheMode().
V obou případech se ujistěte, že nejsou vystavena soukromá data.
Manipulace s tokeny
Pokud váš akční modul nějakým způsobem změní wiki, měl by vyžadovat nějaký token.
Chcete-li to provést automaticky, implementujte metodu needsToken()
, která vrátí token, který váš modul vyžaduje (pravděpodobně 'csrf'
token úprav).
Základní kód API pak automaticky ověří token, který klienti poskytují v požadavcích API v parametru token
.
Pokud nechcete používat token, který je součástí jádra, ale spíše vlastní token s vlastní kontrolou oprávnění, použijte k registraci tokenu háček ApiQueryTokensRegisterTypes .
Přístup k hlavní databázi
Pokud váš modul přistupuje k hlavní databázi, měl by implementovat metodu isWriteMode()
pro návrat true
.
Vracející se chyby
ApiBase zahrnuje několik metod pro provádění různých kontrol, např.
- Pokud potřebujete potvrdit, že byl zadán přesně jeden ze sady parametrů, použijte $this→requireOnlyOneParameter().
- Pokud potřebujete potvrdit, že byl zadán maximálně jeden ze sady parametrů, použijte $this→requireMaxOneParameter().
- Pokud potřebujete potvrdit, že byl zadán alespoň jeden ze sady parametrů, použijte $this→requireAtLeastOneParameter().
- Pokud potřebujete potvrdit, že uživatel má určitá práva, použijte $this→checkUserRightsAny().
- Pokud potřebujete potvrdit, že uživatel může provést akci na konkrétní stránce, použijte $this→checkTitleUserPermissions().
- Pokud je uživatel zablokován (a to je pro váš modul důležité), předejte objekt
Block
objektu $this→dieBlocked().
Často se ale setkáte s případy, kdy potřebujete upozornit na chybu sami.
Obvyklý způsob, jak to udělat, je zavolat $this→dieWithError(), ačkoli pokud máte StatusValue
s chybovými informacemi, můžete je místo toho předat $this→dieStatus().
Pokud potřebujete místo chyby vydat upozornění, použijte $this→addWarning() nebo $this→addDeprecation(), pokud se jedná o upozornění na ukončení podpory.
Dokumentace
API je zdokumentováno pomocí mechanismu MediaWiki i18n. Potřebné zprávy mají obecně výchozí názvy podle "cesty" modulu. U modulů akcí a formátů je cesta stejná jako název modulu použitý při registraci. U submodulů dotazů je to název s předponou query+.
Každý modul bude potřebovat zprávu apihelp-$path-summary
, což by měl být jednořádkový popis modulu.
Pokud je potřeba další text nápovědy, může být vytvořen také apihelp-$path-extended-description
.
Každý parametr bude potřebovat zprávu apihelp-$path-param-$name
a parametry používající PARAM_HELP_MSG_PER_VALUE
budou také potřebovat apihelp-$path-paramvalue-$name-$value
pro každou hodnotu.
Další podrobnosti o dokumentaci API jsou k dispozici na API:Lokalizace .
Rozšíření mohou také dokumentovat své další moduly API na mediawiki.org.
Toto by mělo být umístěno na hlavní stránce rozšíření nebo, pokud je potřeba více místa, na stránkách s názvem Extension:<ExtensionName>/API
nebo jejich podstránkách (např. CentralAuth , MassMessage nebo StructuredDiscussions ).
Jmenný prostor API je vyhrazen pro API jádra MediaWiki.
Rozšíření základních modulů
Od MediaWiki 1.14 je možné rozšířit funkčnost základních modulů pomocí následujících háčků:
- APIGetAllowedParams - přidá nebo upraví seznam parametrů modulu
- APIGetParamDescriptionMessages - přidá nebo upraví popisy parametrů modulu
- APIAfterExecute - udělá něco po provedení modulu (ale před výstupem výsledku)
- Použijte APIQueryAfterExecute pro moduly
prop=
,list=
ameta=
- Pokud je modul spuštěn v režimu generátoru, bude místo toho volán APIQueryGeneratorAfterExecute
- Použijte APIQueryAfterExecute pro moduly
Seznam rozšíření s funkcí API
Viz Kategorie:Rozšíření API pro příklady rozšíření, která přidávají nebo rozšiřují API.
Testování vašeho rozšíření
- Navštivte api.php a přejděte na vygenerovanou nápovědu pro váš modul nebo podmodul dotazu. Informace nápovědy vašeho rozšíření by měly být správné.
- Vzorové adresy URL, které jste uvedli v
getExamplesMessages()
, by se měly objevit v části "Příklady", zkuste na ně kliknout. - Vynechejte a změňte parametry adresy URL v řetězci dotazu, zkontrolujte odpověď svého rozšíření.
- Vzorové adresy URL, které jste uvedli v
- Navštivte Special:ApiSandbox a interaktivně prozkoumejte své API.
- Chcete-li zobrazit další informace o svém rozšíření: