API:Implementation Strategy/ja

これは MediaWiki コアの API の機構の実行方法を説明します. API をコードを書いてクライアントに使用してもらうには をご参照ください.

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

 * はエントリ ポイントであり、ウィキのルート (root) に設置されています. See API:Main page#The endpoint.
 * は API に関連するすべてのファイルを含みますが、それらのうちどれもエントリ ポイントとしては許可されません.
 * すべての API クラスは共通の抽象クラスである  から派生します.  基底クラスは、パラメーターの構文解析、プロファイリング、とエラー処理のような共通の機能を提供します.
 * は  によってインスタンス化されるメイン クラスです.    パラメーターに基づき実行するモジュールを決定します.    は、出力データの配列と関連のヘルパー関数を含む   クラスのインスタンスの作成もします.  最後に   は書式整形クラスをインスタンス化、  から XML/JSON/PHP その他の形式でデータをクライアントに出力します.
 * から派生したどのモジュールもインスタンス化する間に  のインスタンスへの参照を受け取るので、実行の間にモジュールは結果のオブジェクトといった共有リソースを取得することがあります.

クエリ モジュール群
(column_0 > value_0 OR (column_0 = value_0 AND&#xa; (column_1 > value_1 OR (column_1 = value_1 AND&#xa; (column_2 >= value_2)&#xa; ))&#xa;)) Of course, swap ">" for "<" if your  columns are using. Be sure to avoid SQL injection in the values.
 * behaves similar to  in that it executes submodules. Each submodule derives from   (except   itself, which is a top-level module). During instantiation, submodules receive a reference to the ApiQuery instance.
 * All extension query modules should use a 3 or more letter prefixes. The core modules use 2 letter prefixes.
 * execution plan:
 * Get shared query parameters  to determine needed submodules.
 * Create an  object and populate it from the   parameters. The   object contains the list of pages or revisions that query modules will work with.
 * If requested, a generator module is executed to create another . Similar to the piping streams in UNIX. Given pages are the input to generator that produces another set of pages for all other modules to work on.
 * Requirements for query continuation:
 * The SQL query must be totally ordered. In other words, the query must be using all columns of some unique key either as constants in the  clause or in the   clauses.
 * In MySQL, this is an exclusive or, to the point where querying Foo and Bar must order by title but not namespace (namespace is constant 0), Foo and Talk:Foo must order by namespace but not title (title is constant "Foo"), and Foo and Talk:Bar must order by both namespace and title.
 * The SQL query must not filesort.
 * The value given to  must include all the columns in the   clause.
 * When continuing, a single compound condition should be added to the  clause. If the query has , this condition should look something like this:

Internal data structures

 * Query API has had very successful structure of one global nested  structure passed around. Various modules would add pieces of data to many different points of that array, until, finally, it would get rendered for the client by one of the printers (output modules). For the API, we suggest wrapping this array as a class with helper functions to append individual leaf nodes.

Error/status reporting
For now we decided to include error information inside the same structured output as normal result (option #2).

For the result, we may either use the standard HTTP error codes, or always return a properly formatted data:

void header( string reason_phrase [, bool replace [, int http_response_code]] ) The  can be used to set the return status of the operation. We can define all possible values of the, so for the failed login we may return   and  , whereas for any success we would simply return the response without altering the header.
 * Using HTTP code

Pros: It's a standard. The client always has to deal with HTTP errors, so using HTTP code for result would remove any separate error handling the client would have to perform. Since the client may request data in multiple formats, an invalid format parameter would still be properly handled, as it will simply be another http error code.

Cons: ...

This method would always return a properly formatted response object, but the error status/description will be the only values inside that object. This is similar to the way current Query API returns status codes.
 * Include error information inside a proper response

Pros: HTTP error codes are used only for the networking issues, not for the data (logical errors). We do not tied to the existing HTTP error codes.

Cons: If the data format parameter is not properly specified, what is the format of the output data? Application has to parse the object to know of an error (perf?). Error checking code will have to be on both the connection and data parsing levels.