< API:Client code
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
wikitools
mwclient
Pywikibot
Perl
MediaWiki/API
MediaWiki::Bot
Ruby
MediaWiki::Gateway
mediawiki_api
MediaWiki::Butt
Java
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
This article is issued from Mediawiki. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.