API:実装戦略
このページは MediaWiki 操作 API の説明文書の一部です。 |
これは MediaWiki コアの API の機構の実行方法を説明します。 API をコードを書いてクライアントに使用してもらうには API:拡張機能 をご参照ください。
ファイル/モジュール構造
api.php
はエントリ ポイントであり、ウィキのルート (root) に設置されています。 API:メインページ#エンドポイントも参照。includes/api
は API に関連するすべてのファイルを含みますが、それらのうちどれもエントリ ポイントとしては許可されません。- すべての API クラスは共通の抽象クラスである
ApiBase
から派生します。 基底クラスは、パラメーターの構文解析、プロファイリング、とエラー処理のような共通の機能を提供します。 ApiMain
はapi.php
によってインスタンス化されるメイン クラスです。action=XXX
パラメーターに基づき実行するモジュールを決定します。ApiMain
は、出力データの配列と関連のヘルパー関数を含むApiResult
クラスのインスタンスの作成もします。 最後にApiMain
は書式整形クラスをインスタンス化、ApiResult
から XML/JSON/PHP その他の形式でデータをクライアントに出力します。ApiBase
から派生したどのモジュールもインスタンス化する間にApiMain
のインスタンスへの参照を受け取るので、実行の間にモジュールは結果のオブジェクトといった共有リソースを取得することがあります。
クエリ モジュール群
ApiQuery
は下位モジュールを実行するという点でApiMain
と同じ振る舞いをします。 それぞれの下位モジュールはApiQueryBase
から派生します(トップ レベルのモジュールであるApiQuery
自身は除く)。 インスタンス化する間、下位モジュールは ApiQuery のインスタンスへの参照を受け取ります。- 拡張クエリ モジュールはすべて、必ず 3 文字以上の接頭辞を付けます。 コア モジュール接頭辞は 2 文字です。
ApiQuery
の実行計画:- 必要な下位モジュールを決定するために共有クエリ パラメーター
list/prop/meta
を取得する。 ApiPageSet
オブジェクトを作りtitles/pageids/revids
パラメータからそれを投入する。pageset
オブジェクトはクエリ モジュールが連携するページまたは版の一覧を含みます。- 必要な場合、別の
PageSet
を作るために generator モジュールが実行されます。 UNIX でストリームをパイプするのと似ています。 任意のページは取り組む他のすべてのモジュールに対してページの別の一式を生み出す generator への入力です。
- 必要な下位モジュールを決定するために共有クエリ パラメーター
- クエリ継続の必要条件:
- SQL クエリは完全に順序付けする必要があります。 言い換えるなら、クエリはすべての列を使い、特定の固有のキーを
WHERE
節またはORDER BY
節にある定数として提供します。 - SQL クエリは filesort (クイックソート) してはいけません。
setContinueEnumParameter()
に与える値はORDER BY
節の全列を含みます。- 継続するには
WHERE
節に単一の複合条件を追加します。 クエリにORDER BY column_0, column_1, column_2
が含まれると、この条件は以下のようになります:
- SQL クエリは完全に順序付けする必要があります。 言い換えるなら、クエリはすべての列を使い、特定の固有のキーを
(column_0 > value_0 OR (column_0 = value_0 AND (column_1 > value_1 OR (column_1 = value_1 AND (column_2 >= value_2) )) ))
もちろん、ORDER BY
列が DESC
を使用する場合は「>」と「<」を入れ替えます。
値に SQL を導入しないよう注意します。
内部のデータ構造
- クエリの API は 1 つのたらい回しにされるグローバルな入れ子の
array()
構造のとても連続した構造を持ちます。 さまざまなモジュールはデータのピースを多くの異なる配列のポイントに追加し、最後には、それはプリンター (出力モジュール) の 1 つによるクライアントに対してレンダリングされます。 API のために、筆者はこの配列を個別のリーフ ノードを追加するヘルパー関数を持つクラスとしてラップすることを提案します。
エラー/ステータスの報告
これまで開発者達はエラー情報を通常の結果として同じ構造化された出力に含めることを決定しました(オプション #2)。
結果に関して、標準的な HTTP エラー コードを使うまたは適切に整形されたデータを返すかのどちらかを行うことになります:
- HTTP コードを使用
void header( string reason_phrase [, bool replace [, int http_response_code]] )
header()
はオペレーションの戻り値ステータスを設定するために使用できます。
reason_phrase
の可能なすべての値を定義できるので、失敗したログインに関しては code=403
と phrase="BadPassword"
を返す一方で、成功した場合ヘッダーを変えることなく単にレスポンスを返します。
長所: これは標準です。 クライアントは常に HTTP エラーを処理する必要があるため、結果に対する HTTP コードを使用することで実行する個別のクライアント エラー処理を除去します。 クライアントは複数の書式のデータをリクエストするため、無効な書式パラメーターは、別の HTTP エラー コードになることから、まだ適切に処理されます。
短所: ...
- 適切なレスポンス内部のエラー情報を含める
このメソッドは適切に整形されたレスポンス オブジェクトを常に返しますが、エラー ステータス/説明はそのオブジェクト内のみの値になります。 これはクエリ API がステータスコードを返す方法と似ています。
長所: HTTP エラー コードはデータ (論理エラー) ではなくネットワークの問題のためのみに使用されます。 既存の HTTP エラー コードに頼りません。
短所: データ形式パラメーターが適切に設定されていない場合、出力データの形式は何になりますか? エラーを知るためにオブジェクトを解析しなければなりません (perf?)。 エラー チェックのコードは接続とデータ解析レベルの両方に存在しなければなりません。
ボイラープレートコード
このページまたは節は、API:Extensions#ApiSampleApiExtension.php とともに、統合することが提案されています。(議論) |
単純な API モジュール |
---|
<?php
class Api<モジュール名> extends ApiBase {
public function __construct( $main, $action ) {
parent::__construct( $main, $action );
}
public function execute() {
}
public function getAllowedParams() {
return array(
'<パラメーター名>' => array(
ApiBase::PARAM_TYPE => array( 'foo', 'bar', 'baz' ),
),
);
}
public function getParamDescription() {
return array(
'<パラメーター名>' => '<パラメーターの説明>',
);
}
public function getDescription() {
return '<ここにモジュールの説明を記載>';
}
public function getExamples() {
return array(
'api.php?action=<モジュール名>&<パラメーター名>=foo'
);
}
public function getHelpUrls() {
return '';
}
}
|