API:Client code/Evaluations/MediaWiki-Butt

From mediawiki.org

MediaWiki::Butt is a Ruby library for accessing the MediaWiki API. It provides a basic, powerful, feature-rich framework for querying and editing wiki content, as well as administration tasks like updating user rights.

In-depth evaluation[edit]

Easy to install[edit]

Installation instructions are correct and easy to find

Yes There are instructions in the project's README file which detail how to install the library locally through Gemfile as well as RubyGems.

Library is packaged for installation through appropriate package library (rubygems)


Platinum standard: library is packaged for and made available through Linux distributions


Easy to understand[edit]

Well designed--makes all intended API calls available with the intended level of abstraction with no redundancies

Yes There are both high-level and low-level methods for users of different skill levels. Methods for most APIs are available, as well as a public post method in which the user can provide method parameters, headers, and set the return type of either JSON or raw HTTP response.

Platinum standard: makes the Wikidata API available

N Does not make any Wikibase functions available, even at the level of wrapping custom API calls. The methods provided can be used on the Wikidata API endpoint, however.

Well documented
  • Code is commented and readable
Yes YARD comments are present and useful. Different files are easily identifiable for different purposes.
  • Documentation is comprehensive, accurate, and easy to find
Yes RubyDoc linked in the README is hosted through GitHub Pages, and as such, has significantly less downtime than the RubyDoc server. This is the only suggested documentation location.
  • Deprecated functions are clearly marked as such
  • Platinum standard: Documentation is understandable by a novice programmer
Yes Documentation is very entry-level and often uses terms described in the actual MediaWiki API.
Code uses idioms appropriate to the language the library is written in


Easy to use[edit]

Has functioning, simple, and well-written code samples for common tasks

N There are no examples provided in the documentation.

  • Demonstrates edits
N There are no examples provided in the documentation.
Handles API complications or idiosyncrasies so the user doesn't have to
  • Login/logout
  • Cookies
  • Tokens
  • Query continuations
  • Requests via https, including certificate validation
Courteous API usage is promoted through code samples and smart defaults
No code examples provided, but there are smart defaults in the library.
User-Agents default to "NotLoggedIn/MediaWiki::Butt", or, if logged in, that same agent with the username in place of "NotLoggedIn". No examples are provided, but this functionality is documented.
  • Platinum standard: generates a unique user-agent string given name/email address/repository location
  • Efficient usage of API calls
The overall structure of MediaWiki::Butt is an API wrapper with individually wrapped helper methods for common API calls. However, metainformation APIs are supported through more efficient API calls.
  • Uses JSON
Can be used with the most recent stable version of the language it is written in (e.g. Python 3 compatible)

Yes Requires Ruby 2.1 or newer, promoting up-to-date language versions.

Easy to debug[edit]

Contains unit tests for the longest and most frequently modified functions in the library

There are unit tests for the util methods that do not access the API, but not for the most frequently modified and used functions, or the API wrapper methods.

Platinum standard: Unit tests for many code paths exist and are maintained


Terrible hacks/instances of extreme cleverness are clearly marked as such in comments

There are no hacks or extreme cleverness.

Documentation links to the relevant section/subpage of the API documentation


Easy to improve[edit]

MediaWiki::Butt is in semi-active development, so new features are likely to be added on request. Pull requests and bug reports are welcome.

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


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

N The library uses an actual wiki on Gamepedia as its sandbox for testing features and fixes, so the interface only supports versions of the API as new as Gamepedia supports.

Platinum standard: library maintainers contact MediaWiki API maintainers with feedback on the API's design and function


Library specifies the license it is released under


Suggested TODOs[edit]

  • Allow for more efficient API calls, such as listing multiple titles with | or in arrays.
  • Expand API support to various common extensions [1] (in progress).
  • Accurate, practical, and functional tests
  • Creating guides for basic use cases.
  • Test with latest API versions.