This page is part of theMediaWiki Action API documentation.

This explains the implementation of the MediaWiki API machinery in core.If you want to provide an API in your code for clients to consume, readAPI:Extensions.

• api.php is the entry point, located in the wiki root. SeeAPI:Main page#The endpoint.
• ApiEntryPoint is the implementation of the entry point (factored out inGerrit change 959047).
• includes/api will contain all files related to the API, but none of them will be allowed as entry points.
• All API classes are derived from a common abstract classApiBase. The base class provides common functionality such as parameter parsing, profiling, and error handling.
• ApiMain is the main class instantiated byApiEntryPoint. It determines which module to execute based on theaction=XXX parameter.ApiMain also creates an instance of theApiResult class, which contains the output data array and related helper functions. Lastly,ApiMain instantiates the formatting class that will output the data fromApiResult in XML/JSON/PHP or other format to the client.
• Any module derived fromApiBase will receive a reference to an instance of theApiMain during instantiation, so that during execution the module may get shared resources such as the result object.

• ApiQuery behaves similar toApiMain in that it executes submodules. Each submodule derives fromApiQueryBase (exceptApiQuery 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.
• ApiQuery execution plan:
  1. Get shared query parameterslist/prop/meta to determine needed submodules.
  2. Create anApiPageSet object and populate it from thetitles/pageids/revids parameters. Thepageset object contains the list of pages or revisions that query modules will work with.
  3. If requested, a generator module is executed to create anotherApiPageSet. 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 theWHERE clause or in theORDER BY clauses.
    • In MySQL, this is anexclusive or, to the point where queryingFoo andBar must order by title but not namespace (namespace is constant 0),Foo andTalk:Foo must order by namespace but not title (title is constant "Foo"), andFoo andTalk:Bar must order by both namespace and title.
  • The SQL query must not filesort.
  • The value given tosetContinueEnumParameter() must include all the columns in theORDER BY clause.
  • When continuing, a single compound condition should be added to theWHERE clause. If the query hasORDER BY column_0, column_1, column_2, this condition should look something like this:

(column_0 > value_0 OR (column_0 = value_0 AND (column_1 > value_1 OR (column_1 = value_1 AND  (column_2 >= value_2) ))))

Of course, swap ">" for "<" if yourORDER BY columns are usingDESC.Be sure to avoid SQL injection in the values.

• Query API has had very successful structure of one global nestedarray() 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.

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:

Using HTTP code

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

Theheader() can be used to set the return status of the operation.We can define all possible values of thereason_phrase, so for the failed login we may returncode=403 andphrase="BadPassword", whereas for any success we would simply return the response without altering the header.

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: ...

Include error information inside a proper response

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.

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.

It has been suggested that this page or section be merged withAPI:Extensions#ApiSampleApiExtension.php.(Discuss)

<?phpclassApi<modulename>extendsApiBase{publicfunction__construct($main,$action){parent::__construct($main,$action);}publicfunctionexecute(){}publicfunctiongetAllowedParams(){returnarray('<parameter name>'=>array(ApiBase::PARAM_TYPE=>array('foo','bar','baz'),),);}publicfunctiongetParamDescription(){returnarray('<parameter name>'=>'<parameter description>',);}publicfunctiongetDescription(){return'<Module description here>';}publicfunctiongetExamples(){returnarray('api.php?action=<module name>&<parameter name>=foo');}publicfunctiongetHelpUrls(){return'';}}

• MediaWiki action API
• Pages to be merged