API:Client code/Evaluations/MediaWiki-API

MediaWiki::API is a small and low-level Perl API client library that mostly handles direct interactions with the API.

Particularly useful and notable aspects of MediaWiki::API include:
 * Easy-to-follow code and impressively complete documentation, including much useful sample code
 * Handles a lot for such a low-level library (login/tokens/cookies/etc)!
 * Uses API calls efficiently, combining parameters when called for
 * Documentation helpfully links to the documentation for the underlying API

=In-depth evaluation=

Easy to install
No installation instructions are provided with the module. Installation was possible (I used ) but there were problems with file paths and dependencies until I used   to install. Packaged for installation through CPAN. Packaged for Debian: https://packages.debian.org/squeeze/libmediawiki-api-perl. This should be mentioned somewhere in the module documentation.
 * Installation instructions are correct and easy to find
 * Library is packaged for installation through appropriate package library (PyPI, CPAN, npm, Maven, rubygems, etc.)
 * Platinum standard: library is packaged for and made available through Linux distributions

Easy to understand
Low level module, makes all calls accessible and also has helper methods to facilitate login, tokens, etc. The Wikidata API is available when using the Wikidata endpoint.
 * Well designed--makes all intended API calls available with the intended level of abstraction with no redundancies
 * Platinum standard: makes the Wikidata API available
 * Well documented:
 * Code is commented and readable
 * Code has exceptionally useful comments that make the code even more readable. The module is long, however, and should be split into more than one file.


 * Documentation is comprehensive, accurate, and easy to find
 * Docs are up on CPAN.


 * Deprecated functions are clearly marked as such
 * n/a


 * Platinum standard: Documentation is understandable by a novice programmer
 * A novice might be confused, but an advanced beginner will probably be able to use them.

Module uses  and   and is generally written in clear, idiomatic Perl.
 * Code uses idioms appropriate to the language the library is written in

Easy to use
There are code samples provided for most of the methods, as well as a sample script provided in the beginning of the documentation.
 * Has functioning, simple, and well-written code samples for common tasks
 * Demonstrates queries


 * Demonstrates edits


 * Handles API complications or idiosyncrasies so the user doesn't have to:
 * Login/logout


 * Cookies


 * Tokens
 * Handles getting different tokens for different edit actions.


 * Query continuations
 * Handles query continuations for getting lists of pages, but not for other queries.


 * Requests via https, including certificate validation


 * Courteous API usage is promoted through code samples and smart defaults
 * gzip compression is used by default


 * Examples show how to create and use a meaningful and unique user-agent header (as in https://meta.wikimedia.org/wiki/User-agent_policy)
 * Shows where it can be changed but does not mention uniqueness. Default UA includes package name and version.


 * Platinum standard: generates a unique user-agent string given name/email address/repository location


 * Efficient usage of API calls
 * MediaWiki::API is quite low-level but it still retrieves as many parameters at once as possible.


 * Can be used with the most recent stable version of the language it is written in (e.g. Python 3 compatible)

Easy to debug
There are only tests for documentation coverage.
 * Contains unit tests for the longest and most frequently modified functions in the library
 * Platinum standard: Unit tests for many code paths exist and are maintained

n/a; well done.
 * Terrible hacks/instances of extreme cleverness are clearly marked as such in comments
 * Documentation links to the relevant section/subpage of the API documentation

Easy to improve
MediaWiki::API has a single maintainer and no public version control system. Issues are tracked through CPAN's issue tracker. Maintainer reached out to let me know that the library was not abandoned, but there are also some open bug reports/submitted patches from 2012.
 * Library maintainers are responsive and courteous, and foster a thoughtful and inclusive community of developers and users
 * Platinum standard: Project sets clear expectations for conduct for spaces where project-related interactions occur (mailing list, IRC, repository, issue tracker). It should:
 * State desired attitudes and behaviors
 * Provide examples of unwelcome and harassing behavior
 * Specify how these expectations will be enforced

https://rt.cpan.org/Public/Bug/Report.html?Queue=MediaWiki-API states that "The quickest way to report a bug in MediaWiki-API is by sending email to bug-MediaWiki-API [at] rt.cpan.org". As this is not public issue tracker, the speed or responses is not visible. n/a
 * Pull requests are either accepted or rejected with reason within 3 weeks (Platinum standard: 3 business days)
 * Issues/bugs are responded to in some manner within 3 weeks (Platinum standard: 3 business days) (but not necessarily fixed)
 * The library is updated and a new version is released within 3 weeks (Platinum standard: 3 business days) when breaking changes are made to the API
 * Platinum standard: library maintainers contact MediaWiki API maintainers with feedback on the API's design and function

GPL 3
 * Library specifies the license it is released under

=Suggested TODOs=
 * Code-related
 * Consider handling query continuations for other types of queries, not just
 * Offer a method for changing the user-agent
 * Add unit tests
 * Split this module into two or more files to improve ease of use and navigation


 * Process-related
 * Provide instructions for installation
 * Show an example of using a unique user-agent string in the documentation
 * Make it easy for others to contribute through a public version control/issue tracking system
 * Decide and communicate the intended level of responsiveness. If you are interested in MediaWiki::API being listed as a gold standard library, active maintenance and prompt responses are important--even if a given issue is too big to fix immediately or a patch too complex to review quickly.

If these issues are addressed, MediaWiki::API will meet the gold standard and will be listed as such on API:Client code.