API:Client code/Evaluations/MediaWiki-Gateway

MediaWiki::Gateway is a Ruby wrapper around the MediaWiki API. It consists of functions for doing specific tasks--user-rights changes, searches, interwiki links, getting information on revisions, getting article text, etc. The library handles throttling/automatic retries for failed API requests, query continuations for searches and lists, and tokens.

Particularly notable and useful features of MediaWiki::Gateway include:

• Clear description of library status (maintained, but not in development)
• Consistently fast responses to pull requests and issues
• Good test suite
• Consistently documented

In-depth evaluation

Easy to install

Installation instructions are correct and easy to find

N There are instructions telling which commands to use to compile and test MediaWiki::Gateway locally, but no simple installation instructions. I installed version 0.6.0 with gem install mediawiki-gateway.

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

N

Easy to understand

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

The make_api_request method would make the API easily available if it was public. There are a range of helper methods that individually wrap convenient functions. These only cover a portion of the API.

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

RDoc comments are present and useful. However, gateway.rb is very long and should either be refactored to combine common features of individual methods or split into separate files that contain related methods.

• Documentation is comprehensive, accurate, and easy to find

The RubyDoc is clearly linked from README.

• Deprecated functions are clearly marked as such

n/a

• Platinum standard: Documentation is understandable by a novice programmer

N The RubyDoc is long and detailed, without very much context (even in the README). A novice would probably have difficulty getting started.

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

• Demonstrates queries

N

• Demonstrates edits

There are code samples to demonstrate the use of image_info, langlinks, protect, and upload, as well as a sample script demonstrating login and page creation.

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

• 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)

N

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

N

• Efficient usage of API calls

N The overall structure of MediaWiki::Gateway is an API wrapper with individually wrapped helper methods for common API calls. There is no good way to combine multiple helper methods and no easy way to use the API generator module to conserve API calls.

• Uses JSON

N It uses XML by default, and cannot handle JSON.

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

Marked as Ruby 1.8-1.9 compatible; works under 2.1.2 as well.

Easy to debug

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

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

n/a

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

About half the MediaWiki::Gateway methods link to API subpages.

Easy to improve

MediaWiki::Gateway is still maintained but is not in active development, so new features are unlikely to be added on request. However, 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)

Usually, within a few days.

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

Usually, within a few days.

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 is not under active development, so updates are sporadic. However, there is a quick response when pull requests are submitted to fix breaking changes: https://github.com/jpatokal/mediawiki-gateway/pull/58 .

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

MIT license.

Suggested TODOs

Code-related

• Either make make_api_request public or create a method to enable API access for functions that aren't covered by the library
• Continue looking at places to refactor, as in this suggestion for handling continuations: https://github.com/jpatokal/mediawiki-gateway/pull/58
• Add the location of the repository to the default user-agent string
• Some methods already use | to submit multiple pages and properties in an API request--make it possible for more methods to handle lists of pages in a single API request to reduce the number of API calls/bandwidth consumed
• Either state how much of the API the library is intended to cover, or expand the portion of the API that MediaWiki::Gateway makes available

Process-related

• Add basic installation instructions to the README[1]
• Consider adding a short overview section to the documentation to provide new users with an idea of the structure of the library--this would go well with the list of features at the beginning of the README[2]
• Add an example of changing the default user agent to include contact information (as in meta:User-agent policy)[3]
• Add more code samples to the documentation, covering queries as well as edits so that new users have examples to learn from and modify
• Watch mediawiki-api-announce-l for breaking changes that impact the library and make necessary updates within a few weeks
• It is helpful that many of the methods already links to the relevant API subpage; expand this to all methods

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