API:Client code/Evaluations

This page holds evaluations of the client libraries listed on API talk:Client code according to API:Client code/Gold standard. Use the template at the bottom to add your own!

Before evaluating a library, here are some basic questions to consider:

• Has it been updated in the last 12 mo? Does it have a lot of open bugs/pull requests, especially compared to the number closed?
  • If not, consider noting this on the library's entry on API:Client Code.
• Does it have documentation, code samples, and tests provided?
• Does it, at the minimum, handle logins, cookies, and continuations? (Even "syntactic sugar"-type libraries should do at least 2 of these.)

If so, the library is a good candidate for a full evaluation.

Python

simplemediawiki

API:Client code/Evaluations/simplemediawiki

wikitools

API:Client code/Evaluations/wikitools

mwclient

API:Client code/Evaluations/mwclient

Pywikibot

API:Client code/Evaluations/Pywikibot

Perl

MediaWiki::API

API:Client code/Evaluations/MediaWiki-API

MediaWiki::Bot

API:Client code/Evaluations/MediaWiki-Bot

Ruby

MediaWiki::Gateway

API:Client code/Evaluations/MediaWiki-Gateway

mediawiki_api

API:Client code/Evaluations/mediawiki-ruby-api

MediaWiki::Butt

API:Client code/Evaluations/MediaWiki-Butt

Java

Java Wiki Bot Framework (JWBF)

API:Client code/Evaluations/Java Wiki Bot Framework (JWBF)

Template

Library name

[Brief description]

Easy to install

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

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

• Documentation is comprehensive, accurate, and easy to find

• Deprecated functions are clearly marked as such

• Platinum standard: Documentation is understandable by a novice programmer

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

• Demonstrates edits

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)

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

• Efficient usage of API calls

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

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

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

Easy to improve

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

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