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.