API:Extensions/ja

このドキュメントでは、MediaWiki 1.30またはそれ以降での、APIモジュールの作成を扱います。

モジュールの作成と登録

すべての API モジュールは ApiBase のサブクラスですが、派生したベースクラスを使用するタイプのモジュールもあります。 登録の方法もまた、モジュールのタイプに依存します。

actionモジュール

メインの action パラメーターに値を送るモジュールは必ずApiBase をサブクラス化します。 登録には APIModules キーを用いて、extension.json に記載すること。

書式のモジュール

メインのformatパラメーターに値を送るモジュールは必ずApiFormatBaseをサブクラス化します。 登録にはAPIFormatModulesキーを用いてextension.jsonに記載のこと。 拡張機能に書式モジュールが必要な場合は非常にまれです。

クエリの下位モジュール

action=query に prop、list、meta のパラメーターの値を渡すモジュールは、必ず ApiQueryBase (ジェネレーターとして使用できない場合) または ApiQueryGeneratorBase (ジェネレーターとして使用可能な場合) をサブクラス化します。 APIPropModules、APIListModulesもしくはAPIMetaModulesのキーを用いて、必ずextension.jsonに記載します。

どの場合も、登録キーの値はモジュール名を備えたオブジェクト (つまり属性の値) をキーに用い、クラス名はその値とします。 モジュールの登録は条件付で (actionとformatモジュールには) ApiMain::moduleManager と (クエリの下位モジュールには) ApiQuery::moduleManager を用います。

実装

接頭辞

ご利用のAPIモジュールのコンストラクタ関数では、parent::__construct()を呼び出すときにオプションとしてモジュールのパラメーターに接頭辞を指定できます。 (モジュールに関する説明文書を作成すると、この接頭辞が存在する場合にはモジュールの見出しにカッコ入りで表示されます。) ご利用のモジュールがクエリ用下位モジュールである場合、クライアントに正しい動作をさせるため接頭辞が必要です。接頭辞がないと、それぞれ固有のパラメーターを要する複数の下位モジュールを一度に作動させようとしてしまいます。 action及びformatモジュールについては、接頭辞の付与はオプションです。

パラメーター

大半のモジュールにはパラメーターが必要です。 これらは getAllowedParams() を実装することで定義されます。 戻り値は、キーに（接頭辞のない）パラメーター名を取り、値はパラメータのスカラー既定値か、もしくはApiBaseが規定するPARAM_*定数を用いてパラメータのプロパティを定義する配列のいずれかとなります。

サンプルには構文ならびに比較的よく見かけるPARAM_*定数を示します。

	protected function getAllowedParams() {
		return [
			// 既定値のあるオプションのパラメータ
			'simple' => 'value',

			// 必須パラメータ
			'required' => [
				ApiBase::PARAM_TYPE => 'string',
				ApiBase::PARAM_REQUIRED => true,
			],

			// 一覧から複数値を受けるパラメータ
			'variable' => [
				// 値の既定セット
				ApiBase::PARAM_DFLT => 'foo|bar|baz',
				// 許容される値
				ApiBase::PARAM_TYPE => [ 'foo', 'bar', 'baz', 'quux', 'fred', 'blah' ],
				// 複数値を受けることがわかる
				ApiBase::PARAM_ISMULTI => true,
				// 標準の「値単位の」説明メッセージを使用してください
				ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
			],

			// 標準の「制限」パラメータ。一般的に、この標準から逸脱することは推奨されません。
			'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,
			],
		];
	}

パラメータの説明文書はMediaWikiのi18nの仕組み（地域化）に従います。詳細は#説明文書節を参照してください。

実行と出力

モジュールを実行するコードは execute() メソッドを実装します。 一般的にこのコードは $this→extractRequestParams() を使用して入力パラメーターを取得し、出力を追加するためには $this→getResult() を使用してオブジェクト ApiResult を取得します。

クエリ属性の下位モジュールには $this→getPageSet() を用いて、操作するページ群のセットにアクセスします。

ジェネレーターとして使用可能なクエリ下位モジュールの場合も、executeGenerator() の実行が必要で、生成したページ名を入力する ApiPageSet を渡します。 この事例では一般的に、ApiResult を使用すべきではありません。

キャッシュ

API のレスポンスは既定ではキャッシュの対象外です ('Cache-Control: private')! action モジュールにおいて $this→getMain()→setCacheMode() を呼び出すとキャッシュの実行を承認できます。 その場合にも、キャッシュを実際に有効にするにはクライアントが maxage または smaxage パラメーターを渡す必要があります。 $this→getMain()→setCacheMaxAge() を呼ぶと強制キャッシュも可能です。

クエリ モジュールでは、これらのモジュールの呼び出しは禁止です。 その代わりに、getCacheMode() を実装するとキャッシュできます。

いずれの場合にも、個人特定情報をさらさないようにご注意ください。

トークンの処理

程度に関わらずご利用のactionモジュールによりウィキに変更が加えられる場合は、トークンに類するものを備える必要があります。 この処理を自動化するには needsToken() メソッドを実行すると、ご利用のモジュールに必要なトークンを返します。(おそらく 'csrf' として 編集トークンを出力。) するとクライアントが token パラメーターを要求する API に対して提供するトークンは、API ベースコードによって自動的に検証されます。

コアに含まれるトークンではなく、独自の権限チェックでカスタム トークンを使用したい場合は、そのトークンを ApiQueryTokensRegisterTypes フックを使用して登録します。

マスターデータベースへのアクセス

ご利用のモジュールがマスターデータベースにアクセスする場合、true 値を返すために isWriteMode() メソッドを実装する必要があります。

エラーを返す

ApiBaseにはさまざまな点検のために、次の例のような複数の方式があります。

• 一連のパラメーターのうち正確に 1 つが指定されたことを保証する必要がある場合は、$this→requireOnlyOneParameter() を使用します。

• If you need to assert that at most one of a set of parameters was supplied, use $this→requireMaxOneParameter().

• If you need to assert that at least one of a set of parameters was supplied, use $this→requireAtLeastOneParameter().

• If you need to assert that the user has certain rights, use $this→checkUserRightsAny().

• If you need to assert that the user can take an action on a particular page, use $this→checkTitleUserPermissions().

• If the user is blocked (and that matters to your module), pass the Block object to $this→dieBlocked().

それでもなお、自分自身のエラーに対処する必要に迫られる事例にしばしば出会います。 通常の対処方法では $this→dieWithError() を呼び出しますが、代替手段としてエラー情報に関する StatusValue を入手し、$this→dieStatus() に渡すことができます。

エラーメッセージではなく警告を発するには、$this→addWarning() を使用し、廃止を予告するには $this→addDeprecation() を使用します。

説明文書

APIの説明文書にはMediaWikiのi18n地域化の仕組みが使われます。 必要なメッセージは既定でモジュールの「パス」に基づいて命名されます。 actionとformatモジュールに対しては、パスはモジュールの登録時の名称が使われます。 クエリの下位モジュールの接頭辞は query+ が採用されます。

モジュールごとに apihelp-$path-summary メッセージを用意する必要があり、モジュールを1行で簡明に説明します。 さらにヘルプ テキストを設ける場合には apihelp-$path-extended-description を作成できます。 パラメーターごとに apihelp-$path-param-$name メッセージを用意し、PARAM_HELP_MSG_PER_VALUE を用いるパラメーターにも値ごとに apihelp-$path-paramvalue-$name-$value を用意します。

API説明文書の詳細は API:地域化 を参照してください。

拡張機能について、追加の API モジュールを mediawiki.org で 文書化することもできます。 拡張機能のメインページで探すか、空間がさらに必要な場合には Extension:<拡張機能名>/API という名前のページ、またはその下位ページを検索してください (例: CentralAuth 、MassMessage 、StructuredDiscussions )。 MediaWiki コアでは、API 用に API 名前空間が予約されています。

コアモジュールの拡張

MediaWiki 1.14以降、以下のフックを使うことで、コアモジュールの機能を拡張することができます：

• APIGetAllowedParams – モジュールのパラメーター一覧を追加/修正する場合
• APIGetParamDescriptionMessages – モジュールのパラメーターに関する説明を追加/修正する場合
• APIAfterExecute – モジュールの実行後 (ただし結果出力の前) に何か処理をする場合
  • prop=、list=、meta= モジュールには、APIQueryAfterExecute を使用します
    • モジュールをジェネレーター モードで実行したい場合は代わりに APIQueryGeneratorAfterExecute を呼び出します

API機能を備えた拡張機能の一覧

API を追加/拡張する拡張機能の例は カテゴリ:API 拡張機能 を参照してください。

拡張機能の試験

• api.php を開き、ご利用のモジュールに対して作成されたヘルプまたはクエリの下位モジュールへ移動します。 ご利用の拡張機能のヘルプ情報が正しいかどうか、確認する必要があります。
  • getExamplesMessages() で提供したサンプルURL群が「例」に表示されるので、クリックします。
  • クエリ文字列中のURLパラメータを除去したり文字列を一部削除して、拡張機能の反応を試します。
• Special:ApiSandboxを開き、ご利用のAPIをインタラクティブに試用します。
• ご利用の拡張機能に関するその他の情報は、次のリンク先を開いて確認します。$api

api.php?action=paraminfo&modules=myext [ApiSandbox で試用する]