API:Templated parameters/en

As of, API calls may use two level arrays to provide data to the API. This extends the data formats available for API servers to receive arguments from API clients.

Overview
The API structure allows API calls to pass two levels of arguments to an API for evaluation.
 * A module can define a templated parameter like "{fruit}-quantity", where the actual parameters recognized correspond to the values of a multi-valued parameter. Then clients can make requests like "fruits=apples|bananas&apples-quantity=1&bananas-quantity=5".
 * action=paraminfo will return templated parameter definitions separately from normal parameters. All parameter definitions now include an "index" key to allow clients to maintain parameter ordering when merging normal and templated parameters.

Client API
The client can use templated parameters in the same fashion as invoking any web service, using query string arguments or HTTP POST arguments.

Parameter information
The "paraminfo" API query can be used to interrogate the API about the structure of it's parameters.

In this example, the demonstration extension is called ParameterTemplateDemo.

For a development machine example (wiki hosted at machine/wikiprefix), the API test URL would be: http://machine/wikiprefix/api.php?action=paraminfo&modules=ParameterTemplateDemo

which will produce:

Server API implementation
This section aims to aid extension developers who may want to introduce new API's as part of an extension.

Extension addition
Like all extensions, a unique extension directory needs to be added to the MediaWiki's extension directory. In this example, the extension will be named "MyExample".

The LocalSettings.php needs to include a reference to the new extension as

The extension's JSON file be named extension.json in the root directory of the extension folder (in this case /extensions/ParameterTemplatesDemo/extension.json) and include the name, version, description, APIModules, and AutoloadClasses entries. The references to Special Page and Resource Modules are for client side queries.

I18N
The server implementation does rely on a valid i18n directory and JSON file existing, but not yet used in this example.

Implementation class
The implementation class must be in the includes directory. The implementation class must implement the interface of ApiBase.php.

Testing this class can be accomplished by using the built-in API test module. The URL would be http://machine/wikiprefix/api.php?action=ParameterTemplateDemo&fruits=apples|bananas&apples-quantity=1&bananas-quantity=5

A basically a "Hello World," this response just returns what it was passed in with the query string: