On 05/14/2012 02:57 AM, Max Semenik wrote:
On 14.05.2012, 7:04 Kevin wrote:
I propose moving API help to a new special page Special:ApiHelp, which would run a few preg_replace operations and then the parser on individual portions of the documentation to format them as HTML. The combined output for all modules would be cached in memcached as in the old ApiHelp class.
Are you suggesting the removal of the existing API help function from core and the introduction of these missing features into ApiSandbox: a clear, unambiguous "Must POST" indication, "Required" and "Deprecated" markers for parameters, and a way of viewing default parameter values?
Currently, Special:ApiSandbox only serves as a supplement to, not a direct replacement for the complete documentation page, and the documentation at MediaWiki.org will always be out of date or partially irrelevant to an older version of MediaWiki a particular wiki might run (along with the set of installed extensions).
Some API functionality is implemented in the form of specific parameters part of more general modules. For example, one can use action=query&meta=userinfo&uiprop=hasmsg to check for new messages, not the (potentially) confusingly similar meta=allmessages. I am thinking of users who have no prior knowledge of the API or of MediaWiki internals. If users are truly familiar with MediaWiki internals, they might as well just look at the PHP source code in Git.
Do you see a way that Special:ApiSandbox could accommodate a single-page view of all API modules, so that API users can more easily determine which parts of the API they need to use?