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

 * Responsiveness and maintenance
 * Pull requests are responded to (either accepted or rejected with a reason) reasonably quickly [quantify]
 * Issues/bugs are dealt with in a determined period of time [quantify]
 * Library is updated when breaking changes to the API


 * Good coding practices
 * Complete unit test coverage
 * Code is commented and generally readable
 * No terrible hacks


 * Ease of use
 * Documentation is clear and easily accessible
 * Code samples for common uses exist, both for querying and editing

Ruby

 * 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 Ruby library/libraries
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 the API starts only returning JSON. Have not contacted the maintainers yet. --Fhocutt (talk) 05:25, 22 May 2014 (UTC)
 * Mediawiki::Gateway

Python

 * 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

--Fhocutt (talk) 05:14, 21 May 2014 (UTC)
 * 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

Libraries that meet minimum standards:
 * Pywikibot
 * mwclient
 * wikitools (though lack of tests and sparse documentation may knock this down)

Libraries that almost would:
 * simplemediawiki (if it handled continuations, it would)

--Fhocutt (talk) 06:42, 22 May 2014 (UTC)

Perl

 * 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.
 * 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)

-Fhocutt (talk) 21:31, 20 May 2014 (UTC)
 * 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 Perl library

 * Mediawiki::Bot appears to be the only Perl library maintained as of May 2014. Fortunately, it is a fairly good one! Handling continuations would make it better. --Fhocutt (talk) 05:37, 22 May 2014 (UTC)

JavaScript

 * 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 many 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
 * 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:
 * 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
 * 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
 * Has tests, code samples, some documentation
 * Handles continuations, not tokens, not login
 * 1 open/2 closed issues, developer appears responsive


 * mediawiki-api-js
 * Has documentation, some code samples, tests.
 * 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)

Java

 * 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


 * 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.

-Fhocutt (talk) 01:14, 21 May 2014 (UTC)
 * 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