API:Client code/Evaluations/MediaWiki-Butt

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

Easy to install

Installation instructions are correct and easy to find

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

N

Easy to understand

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

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

YARD comments are present and useful. Different files are easily identifiable for different purposes.

• Documentation is comprehensive, accurate, and easy to find

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

n/a

• Platinum standard: Documentation is understandable by a novice programmer

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

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.

• Examples show how to create and use a meaningful and unique user-agent header (as in https://meta.wikimedia.org/wiki/User-agent_policy)

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)

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

Easy to debug

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

N

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

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

N

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

N

Library specifies the license it is released under

Suggested TODOs

Code-related

• 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

Process-related

• Creating guides for basic use cases.
• Test with latest API versions.