API:Extensions/ja

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

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


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


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


 * クエリの下位モジュール
 * や または の値、 の属性値を与えるモジュールは、必ず（ジェネレータとして使用が不可な場合）か（同じく使用可能な場合）をサブクラス化します.  、 もしくは のキーを用いて、必ず に記載します.

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

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

パラメーター
大半のモジュールにはパラメーターが必要です. その設定にはを実行します. 戻り値は、キーに（接頭辞のない）パラメーター名を取り、値はパラメータのスカラー既定値か、もしくはが規定する 定数を用いてパラメータのプロパティを定義する配列のいずれかとなります.

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

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

Execution and output
The code actually implementing the module goes in the method. This code will generally use to get the input parameters, and will use  to get the  object to add any output to.

Query prop submodules should use to access the set of pages to operate on.

Query submodules that can be used as generators will also need to implement which is passed an  that should be filled with the generated pages. In this case, the  should generally not be used.

キャッシュ
By default API responses are marked as not cacheable ('Cache-Control: private')! For action modules, you can allow caching by calling. This still requires clients pass the  or   parameters to actually enable caching. You can force caching by also calling.

For query modules, do not call those methods. You can allow caching by instead implementing.

In either case, be sure that private data is not exposed.

Token handling
If your action module changes the wiki in any way, it should require a token of some kind. To have this handled automatically, implement the  method, returning the token that your module requires (probably the   edit token). The API base code will then automatically validate the token that clients provide in API requests in a  parameter.

Master database access
If your module accesses the master database, it should implement the  method to return.

Returning errors
includes several methods for performing various checks, for example,
 * If you need to assert that exactly one of a set of parameters was supplied, use.
 * If you need to assert that at most one of a set of parameters was supplied, use.
 * If you need to assert that at least one of a set of parameters was supplied, use.
 * If you need to assert that the user has certain rights, use.
 * If you need to assert that the user can take an action on a particular page, use.
 * If the user is blocked (and that matters to your module), pass the  object to.

But you will often run into cases where you need to raise an error of your own. The usual way to do that is to call, although if you have a  with the error information you could pass it to  instead.

If you need to issue a warning rather than an error, use, or if it's a deprecation warning.

説明文書
The API is documented using MediaWiki's i18n mechanism. Needed messages generally have default names based on the module's "path". For action and format modules, the path is the same as the module's name used during registration. For query submodules, it's the name prefixed with "query+".

Every module will need a  message, which should be a one-line description of the module. If additional help text is needed,  may be created as well. Each parameter will need a  message, and parameters using   will also need a   for each value.

More details on API documentation are available at.

Extensions may also maintain extra API documentation on WikiMedia.org. This should be located on the extension's main page or, if more space is required, on pages named  or subpages thereof (e.g. CentralAuth, MassMessage, or StructuredDiscussions). The API namespace is reserved for the API of MediaWiki core.

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


 * APIGetAllowedParams to add or modify the module's parameter list
 * APIGetParamDescription to add or modify the module's parameter descriptions
 * APIAfterExecute to do something after the module has been executed (but before the result has been output)
 * Use APIQueryAfterExecute for,   and   modules
 * If the module is run in generator mode, APIQueryGeneratorAfterExecute will be called instead

List of extensions with API functionality
See API extensions for examples of extensions that add to or extend the API.

Testing your extension

 * Visit [/api.php api.php] and navigate to the generated help for your module or query submodule. Your extension's help information should be correct.
 * The example URLs you provided in  should appear under "Examples", try clicking them.
 * Omit and mangle URL parameters in the query string, check your extension's response.
 * Visit Special:ApiSandbox and interactively explore your API.
 * Visit to see additional information about your extension.