API:Client code/Evaluations/MediaWiki-Butt

From MediaWiki.org
Jump to navigation Jump to search

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)

Yes

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

N

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
n/a
  • 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

Yes

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
Yes
  • Cookies
Yes
  • Tokens
Yes
  • Query continuations
Yes
  • Requests via https, including certificate validation
Yes
Courteous API usage is promoted through code samples and smart defaults
Yellow check.svg No code examples provided, but there are smart defaults in the library.
Yellow check.svg 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
Yes
  • Efficient usage of API calls
Yellow check.svg 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
Yes
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

Yellow check.svg 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

Yes

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

Yes

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)

Yes

Issues/bugs are responded to in some manner within 3 weeks (Platinum standard: 3 business days) (but not necessarily fixed)

Yes

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

Yes

Suggested TODOs[edit]

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.