Jump to content

API:Client code/Evaluations

From mediawiki.org

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

[edit]

simplemediawiki

[edit]

API:Client code/Evaluations/simplemediawiki

wikitools

[edit]

API:Client code/Evaluations/wikitools

mwclient

[edit]

API:Client code/Evaluations/mwclient

Pywikibot

[edit]

API:Client code/Evaluations/Pywikibot

Perl

[edit]

MediaWiki::API

[edit]

API:Client code/Evaluations/MediaWiki-API

MediaWiki::Bot

[edit]

API:Client code/Evaluations/MediaWiki-Bot

Ruby

[edit]

MediaWiki::Gateway

[edit]

API:Client code/Evaluations/MediaWiki-Gateway

mediawiki_api

[edit]

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

MediaWiki::Butt

[edit]

API:Client code/Evaluations/MediaWiki-Butt

Java

[edit]

Java Wiki Bot Framework (JWBF)

[edit]

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

Template

[edit]

Library name

[edit]

[Brief description]

Easy to install

[edit]
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

[edit]
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

[edit]
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
  • 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

[edit]
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

[edit]
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