API:Implementation Strategy/ja

ファイル/モジュール構造
ApiMainはApiResultクラスのインスタンスも作ります(出力データ配列と関連したヘルパー関数を含みます). 最後に、ApiMainはXML/JSON/PHPもしくは他のフォーマットのApiResultからデータをクライアントに出力するclaSsのフォーマッティングをインスタンス化します.
 * api.phpはエントリポイントで、mediawikiのrootに設置されています
 * includes/apiはapiに関連したすべてのファイルを含みますが、それらのうちどれもエントリポイントとしては許可されません
 * すべてのapiクラスは共通の抽象クラスであるApiBaseから派生します. パラメータの解析、プロファイリング、とエラーハンドリングといった基本クラスは共通の機能性を提供します.
 * ApiMainはapi.phpによってインスタンス化されたメインのクラスです. これはaction=XXXパラメータ上に基づいてどのモジュールを実行するか決定します.


 * ApiBaseから派生したどのモジュールもインスタンスになっている間にApiMainのインスタンスへの参照を受け取るので、実行の間にモジュールは結果のオブジェクトといった共有リソースを取得することがあります.

クエリモジュール

 * ApiQueryはサブモジュールを実行するという点でAPiMainと同じ振る舞いをします. それぞれのサブモジュールはApiQueryBaseから派生します(トップレベルのモジュールであるApiQuery自身は除く. インスタンスになっている間、サブモジュールはApiQueryのインスタンスへの参照を受け取ります.
 * ApiQueryの実行プラン:
 * 必要なサブモジュールを決定するために共有クエリパラメータlist/prop/metaを取得する.
 * ApiPageSetオブジェクトを作りtitles/pageids/revidsパラメータからそれを投入する. pagesetオブジェクトはクエリモジュールが連携するページもしくはリビジョンの一覧を含みます. モジュールの中には単独のページのみを含むpagesetを必要とするものがあることにご注意お願いします.
 * 必要な場合、別のPageSetを作るためにgeneratorモジュールが実行されます - UNIXでストリームをパイプするのと似ています - 任意のページは取り組む他のすべてのモジュールに対してページの別の一式を生み出すgeneratorへの入力です.

内部のデータ構造
筆者はこの配列を個別のleafノードを追加するヘルパー関数を持つクラスとしてラップすることを提案します.
 * クエリのAPIは1つのたらい回しにされるグローバルな入れ子のarray構造のとても連続した構造を持ちます. 様々なモジュールはデータのピースを多くの異なる配列のポイントに追加し、最後には、それはprinters(output modules)の1つによるクライアントに対してレンダリングされます. APIのために、

エラー/ステータスの報告
これまで開発者達はエラー情報を通常の結果として同じ構造化された出力に含めることを決定しました(オプション #2).

結果に関して、標準的なHTTPエラーコードを使うもしくは適切にフォーマットされたデータを返すかのどちらかを行うことになります:

void header( string reason_phrase [, bool replace [, int http_response_code]] ) The headerはオペレーションの返り値ステータスを設定するために使うことができます. reason_phraseの可能なすべての値を定義できるので、失敗したログインに関してはcode=403とphrase="BadPassword"を返す一方で、成功した場合ヘッダを変えることなく単にリスポンスを返します.
 * HTTPコードを使う

Pros:これは標準です. クライアントは常にhttpエラーを取り扱わなければなりませんので、結果に対するhttpコードを使うことで実行する個別のクライアントエラーハンドリングを除去します. クライアントは複数のフォーマットのデータをリクエストするので、無効なフォーマットパラメータは、別のhttpエラーコードになるので、まだ適切に処理されます.

Cons: ...

このメソッドは適切にフォーマットされたリスポンスオブジェクトを常に返しますが、エラーステータス/説明はそのオブジェクト内のみの値になります. これはクエリAPIがステータスコードを返す方法と似ています.
 * 適切なリスポンス内部のエラー情報を含める

Pros: HTTPエラーコードはデータ(論理エラー)ではなくネットワーキング問題のためのみに使われます. 既存のHTTPコードに頼りません.

Cons: data formatパラメータが適切に設定されていない場合、出力データのフォーマットは何になりますが？エラーを知るためにオブジェクトを解析しなければなりません(perf?). エラーチェックのコードは接続とデータ解析レベルの両方に存在しなければなりません.