API:Implementation Strategy/ja

このページは MediaWiki API 説明文書の一部です。

言語:	English  • 日本語

MediaWiki API

Quick overview:

• Quick start guide
• FAQ
  • エチケットおよび使用制限
• チュートリアル
• フォーマット
• エラーの報告
• 使用制限
• クロスサイト リクエスト
• 認証
  • ログイン
  • ログアウト
  • アカウント作成
• クエリ
  • メタ情報
  • プロパティ
  • 一覧
• 検索の提案
• ウィキテキストの構文解析とテンプレートの展開
• ページのキャッシュの破棄
• パラメーター情報
• ウィキの本文の変更
  • ページの作成/編集
  • ページの移動
  • ロールバック
  • ページの削除
  • 削除された版の復元
  • ページの保護/保護解除
  • 利用者のブロック/ブロック解除
  • ページのウォッチ/ウォッチ解除
  • ウォッチしているページの版を訪問済みにする
  • メールの送信
  • 変更の巡回
  • ページの取り込み
  • 利用者の所属グループの変更
  • ファイルのアップロード
  • 利用者オプション
  • トークン
• ウォッチリストのフィード
• ウィキデータ /en
• 拡張機能
• MediaWikiおよび拡張機能内でのAPIの使用
• その他
• 実装
• クライアント コード
• アサート

ファイル/モジュール構造

• api.phpはエントリポイントで、mediawikiのrootに設置されています
• includes/apiはapiに関連したすべてのファイルを含みますが、それらのうちどれもエントリポイントとしては許可されません
• すべてのapiクラスは共通の抽象クラスであるApiBaseから派生します。パラメータの解析、プロファイリング、とエラーハンドリングといった基本クラスは共通の機能性を提供します。
• ApiMainはapi.phpによってインスタンス化されたメインのクラスです。これはaction=XXXパラメータ上に基づいてどのモジュールを実行するか決定します。

ApiMainはApiResultクラスのインスタンスも作ります(出力データ配列と関連したヘルパー関数を含みます)。最後に、ApiMainはXML/JSON/PHPもしくは他のフォーマットのApiResultからデータをクライアントに出力するclaSsのフォーマッティングをインスタンス化します。

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

クエリモジュール

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

内部のデータ構造

• クエリのAPIは1つのたらい回しにされるグローバルな入れ子のarray()構造のとても連続した構造を持ちます。様々なモジュールはデータのピースを多くの異なる配列のポイントに追加し、最後には、それはprinters(output modules)の1つによるクライアントに対してレンダリングされます。APIのために、

筆者はこの配列を個別のleafノードを追加するヘルパー関数を持つクラスとしてラップすることを提案します。

エラー/ステータスの報告

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

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

HTTPコードを使う

void header( string reason_phrase [, bool replace [, int http_response_code]] )

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

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

Cons: ...

適切なリスポンス内部のエラー情報を含める

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

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

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