Last modified: 2012-04-16 09:16:04 UTC
The Mediawiki API documentation at http://en.wikipedia.org/w/api.php is incomplete. It should mention that there is a "MediaWiki-API-Error" header returned with erroneous requests. There's also no documentation of how to use the maxlag parameter.
Maxlag is documented at the top of the page
Maxlag appears to be documented only as "maxlag - Maximum lag" which I'm not sure is very helpful. :) There is a prominent link to http://www.mediawiki.org/wiki/API ... but there's no obvious link to maxlag info there either. If you search on mediawiki.org you can turn up this page: http://www.mediawiki.org/wiki/Manual:Maxlag_parameter Perhaps we can have the help link to some of these detail pages directly?
(In reply to comment #2) > Maxlag appears to be documented only as "maxlag - Maximum lag" which I'm not > sure is very helpful. :) > > There is a prominent link to http://www.mediawiki.org/wiki/API ... but there's > no obvious link to maxlag info there either. > > If you search on mediawiki.org you can turn up this page: > > http://www.mediawiki.org/wiki/Manual:Maxlag_parameter > > Perhaps we can have the help link to some of these detail pages directly? People should think themselves lucky they get any documentation at ALL! =D
@Reedy The lack of documentation is abhorrent. This isn't a half-baked alpha API, and neither is this a proprietary API...this is supposed to be FOSS. A public API isn't meant to be an exercise in reverse engineering...
(In reply to comment #4) > @Reedy > > The lack of documentation is abhorrent. This isn't a half-baked alpha API, and > neither is this a proprietary API...this is supposed to be FOSS. > > A public API isn't meant to be an exercise in reverse engineering... That at best, is slightly an overstatement. The API pro-rata to most of the project is well documented, both with the internal and the more external facing documented. Granted, it's not perfect, but what FOSS project is. When you don't pay people to write documentation, chances are, they won't. This seems very reverse to what most people have said, with it often being reasonably well congratulated of it being there. Even when I was using 3-4 years ago as just a consumer, I rarely had any difficulties, usually it was when using strange parameter combinations, but it was worked out. Similarly, if it is "so abhorrent", why don't we have more complaints of things being bad? Usually people have nitpicks over little bits and pieces, but it's never "OMG THE DOCUMENTATION IS SO BAD I CANT FUCKING USE THIS" Unfortunately we are both not mind readers, and also mixed ability end user consumers. We can't work out what you think is wrong, so unless people tell us, it's a wild stab in the dark. And on that the only issues you seem to bring up, is 1 poorly documented parameter, and the fallback "error" which brings you to the help page in a lot of cases. I've no idea how you get from 2 omissions/errors
Maxlag documentation fleshed out on API inbuilt help in r89461
MW.org http://www.mediawiki.org/w/index.php?title=API%3AMain_page&action=historysubmit&diff=407748&oldid=401839
r89505 adds the information about erroneous requests to the API help output
closing. Please refrain from reopening unless you have some specific thing that you think needs to be documented better and that isn't addressed by the above comments.
