API talk:Client code

Is there an objective-C library? 74.202.39.3 19:05, 14 January 2013 (UTC)

= Client library evaluation = As a part of my OPW internship project, I'll be developing standards for MediaWiki-Recommended-Client Libraries. As a part of this process I'm evaluating existing libraries in Python, Perl, Ruby, JavaScript, and Java. While this is in progress I'll be posting my initial evaluations on this page. Fhocutt (talk) 20:22, 20 May 2014 (UTC)

Initial screening criteria

 * Mandatory
 * Has it been updated in the last 12 mo (i.e. since May 2013)?
 * Listed these separately on API:Client code. Only further evaluating currently-supported ones. Fhocutt (talk) 20:22, 20 May 2014 (UTC)
 * Does it, at the minimum, handle logins/cookies/continuations? (even "syntactic sugar" libraries should do these things)
 * Warning signs
 * Does it have a lot of open bugs/pull requests, especially compared to the number closed?
 * Does it provide inadequate documentation, code samples, or tests?

Proposed "gold standard" criteria
The web API client libraries available on API:Client code enable developers to easily and intuitively interact with the MediaWiki API. The libraries currently listed vary widely in capabilities, maintenance status, and code/documentation quality. To make it easier for new users of the API to find a library that meets their needs, we're introducing a "gold standard" that will indicate particularly high-quality, currently-maintained libraries. We also hope that the standard will also help library developers decide how to focus their efforts so that the code they create can be easily used by expert and novice developers alike.

We believe that a good client library should be easy to install, easy to understand, easy to use, easy to debug, and easy to improve. As such, accessible documentation is as important as elegant code. Unless otherwise indicated, the items below belong to the "gold standard": challenging but within reach. The items marked "platinum standard" indicate that library developers and maintainers have gone above and beyond the "gold standard", resulting in an exceptional library.


 * 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
 * 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
 * Platinum standard: generates a unique user-agent string given name/email address/repository location
 * Efficient usage of API calls
 * 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
 * [''See the Rust language's conduct policy for a good example]
 * 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

Edited to draft #2. --Fhocutt (talk) 05:12, 28 May 2014 (UTC)

Comments
Please leave comments on other features of a great API client library that are missing here, or any criteria above that you do not think are essential/reasonable. --Fhocutt (talk) 06:43, 23 May 2014 (UTC)

From IRC chat with Mithrandir:
 * consider packaging for distros?
 * Way beyond gold standard, probably beyond platinum
 * consider MSI for Windows? (not common)
 * "it should be easy to get help with the library, via lists, irc or forums"
 * ...with some form of enforced community standards? i.e. friendly space/code of conduct/similar. Not currently something any of these have to my knowledge but I'd like to see it. --FH
 * Something like Rust's: http://www.reddit.com/r/rust/comments/1nvsdh/a_note_on_conduct_please_read/
 * have a "gold standard" and "platinum standard" list, moving items to "gold standard" as libraries get there
 * possibly a pie-in-the-sky list
 * easy to use => "uses language idioms"
 * maybe quantify "reasonable length of time", maybe not--"a couple of weeks" perhaps, which is not "a month" to most people
 * is there an established way to deal with this?
 * complete coverage for unit tests is a high and sometimes-pointless bar
 * find out best QA practices and require those
 * something more like "all MW API functions' functions have tests"? "all real functions" (needs better phrasing)/more precise phrasing for "reasonable test coverage" <--- consider the reason for the standard?


 * it would be pie-in-the-sky amazing if the client lib maintainers actually had contacted us in the past for any reason, I think --sumanah
 * handles wikidata/wikibase functions: platinum/pie-in-the-sky

Best Ruby library
Has the most features of the available libraries and is maintained as of May 2014, but is not in active development. Accepts XML results only, which will be a problem when (if?) the API starts only returning JSON. Have not contacted the maintainers yet. --Fhocutt (talk) 05:25, 22 May 2014 (UTC) Have spoken to a patch submitter--maintainer is responsive, friendly, actively welcomes patches. Commented that the library is very Rubyish. --Fhocutt (talk) 15:29, 1 June 2014 (UTC)
 * Mediawiki::Gateway

Maintained Ruby libraries

 * mediawiki/ruby/api, https://gerrit.wikimedia.org/r/#/admin/projects/mediawiki/ruby/api - Ruby API client library in active development as of April 2014
 * wikipedia-client - Ruby framework using the API.
 * MediaWiki::Gateway - Ruby framework for the API. Maintained, tested up to MediaWiki 1.22, compatible with Wikimedia wikis. Has not been in active development since 2012 but docs say patches are welcome.


 * mediawiki/ruby/api comments:
 * Only one open issue that I could find (Bugzilla/Gerrit)
 * Does not cover most common API functions; does appear to handle logins, tokens, cookies
 * Has tests, next to no documentation, one code sample


 * wikipedia-client comments:
 * Does not appear to handle continuations
 * 5 open/16 closed issues (3 issues are pull requests < 3 weeks old)
 * Has tests.
 * Has minimal documentation
 * Does not handle cookies, login, but offers abstraction and ease of use for common GET API calls

--Fhocutt (talk) 22:39, 20 May 2014 (UTC)
 * MediaWiki/Gateway comments:
 * Handles login, cookies, continuations, queries, editing/moving/protecting
 * Provides a selection of example scripts: https://github.com/jpatokal/mediawiki-gateway/tree/master/samples
 * 10 open/43 closed issues (open ones are mostly from 2011-2012)
 * Docs exist. No tests.

Best Python libraries
Libraries that meet initial criteria:
 * Pywikibot (most features, geared towards bot-writers and power users)
 * mwclient (easiest for a novice developer to use for queries)
 * wikitools (though lack of tests and sparse documentation may knock this down)

Close:
 * simplemediawiki does not automatically handle continuations or tokens but is a lightweight, accessible, and functional API wrapper.

Maintained Python libraries

 * Pywikibot - A collection of python scripts. Seems up to date (Nov 2013) (IRC)
 * [//github.com/mwclient/mwclient mwclient] - A Python library that makes most of the API functions accessible. ([//pypi.python.org/pypi/mwclient/ PyPI])
 * wikitools - Provides several layers of abstraction around the API. Should be up to date ([//pypi.python.org/pypi/wikitools PyPI])
 * Wikipedia - A Python library that makes it easy to access and parse data from Wikipedia. (PyPI)
 * [//github.com/ianweller/python-simplemediawiki simplemediawiki] - A simple, no-abstraction interface to the API. Handles cookies and other extremely basic things. Python 2.6+ and 3.3+ compatible. ([//pypi.python.org/pypi/simplemediawiki PyPI])
 * [//github.com/legoktm/supersimplemediawiki supersimplemediawiki] - Similar to simplemediawiki, but does not handle tokens or compression.
 * Pattern, - web mining module, has classes for handling MediaWiki API requests, handles continuations


 * Pywikibot comments
 * Has lots of features and is aimed at bot-writers and power users, not users who want to retrieve data. The documentation in particular is extensive, but aimed at bot-making and is not newbie-developer friendly.
 * Has a number of scripts to handle common wiki-editing tasks, but none I could find for retrieving data
 * Handles tokens, cookies, logins, continuations, compression
 * 445 closed/226 open bugs (in Bugzilla)
 * Is the only Python library in this list that explicitly handles wikibase API calls
 * Has tests


 * mwclient comments
 * Handles compression, tokens, cookies, login, continuations
 * Has some code samples, minimal documentation, tests
 * 13 open/26 closed issues
 * quick response to reported documentation issue: https://github.com/mwclient/mwclient/issues/39 --Fhocutt (talk) 20:41, 22 May 2014 (UTC)


 * wikitools comments
 * Handles continuations, compression, cookies, login
 * Has some code samples, minimal documentation, no tests
 * 5 open/5 closed issues


 * Wikipedia comments
 * Has code samples, some documentation, tests
 * 1 open/44 closed issues, seems up-to-date
 * Handles continuations, no tokens, no cookies, no login


 * simplemediawiki comments
 * Handles compression, cookies, login, logout, but not continuations, you can make whatever API calls you want (low-level wrapper)
 * Has reasonable documentation, code samples (could be easier to find), tests
 * 2 open/7 closed issues


 * supersimplemediawiki comments
 * Handles cookies and logins but not continuations or tokens
 * Minimal documentation, no tests; a code sample is provided but an open issue says it does not run; rejected patch that added token handling and logout capability
 * 2 closed/3 open requests


 * Pattern comments
 * Part of a larger set of libraries for data mining, natural language processing, network analysis, etc.
 * Has documentation, code samples, tests
 * Does not appear to support login/cookies

Best/Only maintained Perl library

 * MediaWiki::Bot - A higher-level Perl module with read and write functions. Easily extensible with plugins, for example to provide administrator functions. Updated Jan 2014. Does not handle continuations; this would improve it.
 * Documentation Wikibook (very out of date, bug filed: https://github.com/MediaWiki-Bot/MediaWiki-Bot/issues/56)
 * source code on Github
 * Google Code project (updated 2011)
 * Client scripts (updated 2010)


 * MediaWiki/Bot comments:
 * The most recent release is on CPAN, the most recent development version is on github.
 * Handles logins and cookies; supports continuations for image search but only searches up to max limits for the other methods.
 * Has tests, has documentation, has code samples, has 13 open/43 closed issues. Most of the open issues are c. 2011.

Best JavaScript libraries
None of these libraries meet all of the initial criteria. Generally, the best of these either handle continuations or tokens/login.

The closest to meeting the criteria are:
 * nodemw (no continuations)
 * MediaWiki (no continuations)
 * WikiJS (no tokens/login)

The mediawiki.api.js module (no continuations/logout; doesn't offer plugins for many common tasks) ships with MediaWiki core, but appears to be not nearly as versatile as nodemw or MediaWiki.

Maintained JavaScript libraries

 * https://github.com/macbre/nodemw - Node.js client, actively maintained as of May 2014.
 * mediawiki-js (npm) Ultra-light, vanilla JavaScript wrapper of Mediawiki API for use in the browser
 * Node.js MediaWiki module - A JavaScript framework of standard requests (e.g. log in, log out, read, edit, etc.) as well as a general wrapper method. Includes some helpful stuff like throttling.
 * WikiJS - a simple node.js library that serves as an interface to MediaWiki
 * mediawiki.api.js - A module that ships with MediaWiki core, abstracts a few API calls into simple one liners (uses  internally).

These are libraries for making generic web requests, not API client libraries:
 * jQuery.ajax - Not specifically made for the MediaWiki API, but most queries are very simple with one or two lines of using  or.
 * Reactive Extensions for JavaScript - also not specifically made for the MediaWiki API but supports throttling and MediaWiki API calls


 * nodemw comments
 * Handles login, tokens, probably not continuations
 * Has tests, code samples, collection of scripts for common requests, decent documentation, handles queries, edits, etc.
 * 1 pending pull request from 30 April 2014, 5 open/33 closed issues


 * mediawiki-js comments
 * Very lightweight wrapper around API queries--does minimal protocol handling and result parsing, no continuations
 * Cannot be used for logged-in requests (uses jsonp, signified by use of "callback" parameter)
 * Appears to be a new repository as of May 2014? 0 issues, 0 pull requests
 * Has sample script and other code samples, minimal documentation


 * MediaWiki comments
 * Handles queries, edits, login/logout, tokens, but not continuations
 * Has good documentation, code samples, but no tests
 * New project, 0 issues/0 pull requests (Correction: 1 feature request: https://github.com/oliver-moran/mediawiki/issues/1 --Fhocutt (talk))


 * WikiJS comments
 * Has tests, code samples, some documentation
 * Handles continuations, not tokens, not login
 * 1 open/2 closed issues, developer appears responsive


 * mediawiki-api-js comments
 * Has documentation, some code samples, tests. Included in mediawiki-core.
 * Handles tokens, login, but not logout or continuations. Has plugins for a small handful of common tasks (edit, category search, watch/unwatch). Looks like it's possible to use it for generic API calls.
 * Could find one issue with this Bugzilla search; there may be more. --Fhocutt (talk) 21:25, 22 May 2014 (UTC)

Best Java libraries
All of these except for possibly WPCleaner appear to meet the initial criteria. WPCleaner is not documented or laid out clearly as an easily reusable API client library and since the other 3 appear to be maintained and documented well and are full-featured, evaluating them should be sufficient.

''This could use another set of eyes from someone with Java experience. --Fhocutt (talk) 02:31, 23 May 2014 (UTC)''

Maintained Java libraries

 * Bliki Engine - Java Wikipedia API - very complete. Can convert wikicode to HTML, DocBook or PDF. Has a helper library for API calls.
 * JavaWikiBotFramework - a Java library that makes almost all API functions accessible. On github: https://github.com/eldur/jwbf.
 * Wiki.java — a simple one-class API implementation
 * WPCleaner — a Java editing tool that includes a package for MediaWiki API.


 * Blicki/MediaWikiAPISupport comments:
 * Appears to handle continuation, login
 * in active development; hard to sort out API issues from Bliki parser issues
 * Has tests, has code samples, is commented for JavaDoc but I couldn't find a compiled full set of documentation
 * API code seems to be built really along the lines of something that parses pages -- e.g. the Page object does not seem to support saving new text to pages.


 * JavaWikiBotFramework comments:
 * Appears to be fairly full-featured; definitely handles login, cookies, continuations
 * 2 open issues, 11 closed, no pending pull requests
 * Has documentation, some code samples, tests


 * Wiki.java comments:
 * Handles login, cookies, continuations, variety of GET/POST requests
 * Has documentation (JavaDoc and extended documentation), code sample, and tests
 * In active development as of May 2014; 6 open issues, 47 closed, most from 2010.
 * Uses string functions a lot where specific libraries should be used -- e.g. builds URL's by concatenating strings and parses XML with line.indexOf("<page ").


 * WPCleaner comments:
 * WPCleaner is a stand-alone tool with a package that handles the MediaWiki API. It has tests and a JavaDoc but it's not clear to me what that package specifically does. -Fhocutt (talk) 00:10, 21 May 2014 (UTC)
 * Issue reporting is on the talk pages, which get responses