Page MenuHomePhabricator

Mediawiki API documentation incomplete
Closed, ResolvedPublic

Description

Author: M8R-udfkkf

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


Version: unspecified
Severity: normal

Details

Reference
bz29265

Event Timeline

bzimport raised the priority of this task from to Lowest.Nov 21 2014, 11:25 PM
bzimport added a project: MediaWiki-API.
bzimport set Reference to bz29265.

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

M8R-udfkkf wrote:

@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

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.