The current Mediawiki API documentation is on the terse side, and occasionally on the outdated one, as well. I'll name a few particular examples I have run across while writing a tool on Tool Labs recently, but it needs love throughout.

Examples:

1. The use of continue, essential for most useful query actions, is not introduced on the main page, nor mentioned in the tutorial page. This is particularly painful considering the continue behavior has changed not so long ago, and some API client libraries have not updated yet, leading tool developers (like yours truly) to look for documentation to patch their clients.
2. speaking of client libraries, there is no prominent link on the main page to the various clients available, other than at the (very bottom of) TOC box on the right. I think it is a safe bet that most people consulting that page would be delighted to use an existing client rather than roll their own raw API calls, so perhaps some mention of and link to the clients should be made earlier and/or more prominently.
3. many API pieces, particularly props and lists, have very scanty examples, making it difficult to determine common usage or, conversely, nonsensical parameter combinations. For instance (this happened to me last week), it was not readily apparent how to obtain a thumbnail url from the API, and the imageinfo documentation does its best to hide the answer among dozens of parameters. It would have been great to have it clearly spell out that specifying a combination of an iiprop including url and providing a desired iiurlwidth would do the trick.

Thanks in advance!