API:Client code/Evaluations/Java Wiki Bot Framework (JWBF)
Java Wiki Bot Framework is a Java framework, intended to make it easy to write Java bots that interact with the MediaWiki API. It handles login/logout, cookies, query continuations, and tokens, and has a range of helper methods for common tasks as well as for basic interaction with the MediaWiki API.
Particularly notable or useful features of JWBF include:
- Designed and implemented as framework for writing bots
- Solid codebase and a good set of features
- Has frequently updated unit and integration tests
- A responsive and helpful maintainer
Easy to install
[edit]- Installation instructions are correct and easy to find
No installation instructions.
- 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
It is unusual to ship Java packages with Linux distributions.
Easy to understand
[edit]- Well designed--makes all intended API calls available with the intended level of abstraction with no redundancies
Intended as a framework, so exposes the lower-level API calls. Also has many helper methods.
- Platinum standard: makes the Wikidata API available
In progress: Basic Queries - Fast forward branch - Exchange with Wikidata Toolkit
- 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
- Documentation is very sparse and does not make it easier for someone new to Java to understand the structure of the JavaDoc.
- Code uses idioms appropriate to the language the library is written in
Adequately written Java.
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
- Uses the new
continue
parameter for newer versions of the API.
- Requests via https, including certificate validation
- Test Login with override default certificate validation
- Courteous API usage is promoted through code samples and smart defaults
- gzip compression is used by default
- There are tests (
HttpBotTest
andHttpActionClientTest
) that proves that gzip is the 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
- see documentation(Commit b1abbc8)
- Efficient usage of API calls
- API calls are combined when working in multiple namespaces, but not in other ways (combining requests for multiple titles/users/etc.)[1]
- 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
The framework has integration tests as well.
- Terrible hacks/instances of extreme cleverness are clearly marked as such in comments
Comments include TODOs and comments like "not sure if this is the best way"
- 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
Maintainer is actively involved and helpful.
- 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)
none submitted
- Issues/bugs are responded to in some manner within 3 weeks (Platinum standard: 3 business days) (but not necessarily fixed)
There is usually a response within 1-2 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/a
- 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
Apache 2.0
Suggested TODOs
[edit]- Code-related
- Make efficient usage of API calls easier, possibly by creating a method that combines calls for multiple items (e.g.
title1|title2|title3|...
).[2]
- Process-related
- Improve documentation, especially the JavaDoc. Consistently add method and class descriptions.[3]
If these issues are addressed, Java Wiki Bot Framework will meet the gold standard and will be listed as such on API:Client code.