API talk:Client code

From mediawiki.org
Latest comment: 2 years ago by Adamw in topic Ongoing evaluation?

Is there an objective-C library? 19:05, 14 January 2013 (UTC)Reply[reply]

Client library evaluation[edit]

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)Reply[reply]

Initial screening criteria[edit]

  • Has it been updated in the last 12 mo (i.e. since May 2013)?
  • 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?


Best Ruby library[edit]

  • Mediawiki::Gateway

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)Reply[reply]

Maintained Ruby libraries[edit]

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
MediaWiki/Gateway comments

--Fhocutt (talk) 22:39, 20 May 2014 (UTC)Reply[reply]


Best Python libraries[edit]

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)


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

Maintained Python libraries[edit]

  • Pywikibot - A collection of python scripts. Seems up to date (Nov 2013) (IRC)
  • mwclient - A Python library that makes most of the API functions accessible. (PyPI)
  • wikitools - Provides several layers of abstraction around the API. Should be up to date (PyPI)
  • Wikipedia - A Python library that makes it easy to access and parse data from Wikipedia. (PyPI)
  • simplemediawiki - A simple, no-abstraction interface to the API. Handles cookies and other extremely basic things. Python 2.6+ and 3.3+ compatible. (PyPI)
  • supersimplemediawiki - Similar to simplemediawiki, but does not handle tokens or compression.
  • Pattern, [1] - 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.
    How is it not "newbie-developer friendly"? Legoktm (talk) 19:40, 9 June 2014 (UTC)Reply[reply]
    It may be better for new developers who know they want to write bots, but that's not the only use for a client library. I couldn't figure out how to use it to perform queries or otherwise extract page data, and neither could a friend of mine. There's a lot of information, and if all you know is that you want to use a client library to write a Python script but probably don't want to write a bot, the docs don't provide easily-digestible information to get from point A to point B. Fhocutt (talk) 23:44, 11 June 2014 (UTC)Reply[reply]
  • 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
  • Is, in theory, able to fallback to screenscraping when API is disabled or unavailable. (Not currently tested.)
mwclient comments
wikitools comments
  • Handles continuations, compression, cookies, login
  • Has some code samples, minimal documentation, no tests
  • 5 open/5 closed issues
Wikipedia comments
  • Has some sample code, introductory documentation and some tests.
  • 21 open/40 closed issues, more than a year has passed without new pushes in master branch.
  • Handles continuations but no tokens, no cookies, no login.
  • It is easy to install but it gives few comments on how it does it. It is sort of easy to get what it does and how, it would be fair to debug or improve.
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


Best/Only maintained Perl library[edit]

  • This module relies on the MediaWiki-API module, which handles the lower-level interactions with the API. Although MediaWiki-API has not been updated since 2012, it is not abandoned and patches/pull requests are welcome.
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[edit]

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

  • 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 jQuery.ajax internally).

These are libraries for making generic web requests, not API client libraries:

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
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)Reply[reply]

Question: JQuery and MW.API[edit]

Wondering why JQuery isn't mentioned on the list. I would wager that it is the second most common JavaScript client behind the MediaWiki JavaScript API, which is based on JQuery. Iowajason (talk) 00:50, 17 November 2015 (UTC)Reply[reply]


Best Java libraries[edit]

All of these except for possibly en:WPCleaner appear to meet the initial criteria. en: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)Reply[reply]

Maintained Java libraries[edit]

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)Reply[reply]
  • Issue reporting is on the talk pages, which get responses

libmediawiki C++[edit]

Seems to be currently very active, ref https://projects.kde.org/projects/extragear/libs/libmediawiki/activity. Rursus (talk) 16:06, 15 March 2015 (UTC)Reply[reply]

I updated the C++ section. Rursus (talk) 16:10, 15 March 2015 (UTC)Reply[reply]


The mediawiki-api-base and mediawiki-api wrappers work and are actively updated. However the manual states you only need to add the composer preload. Most likely because of a Farm situation this did not work for me. Including Webstart.php instead did the job.

Ongoing evaluation?[edit]

Library evaluation is a good idea, but has gotten very sporadic attention over the years. Perhaps we can combine the "All" subpage into this table, and include each library's current evaluation or pending status as its own column? See also my comments on that talk page. Adamw (talk) 23:01, 6 December 2021 (UTC)Reply[reply]