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?

Ruby

Best Ruby library

• 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)

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

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.

--Fhocutt (talk) 22:39, 20 May 2014 (UTC)

Python

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)
• 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)

  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)

• 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

• 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 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

• 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

Perl

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)

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

JavaScript

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 jQuery.ajax 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 $.getJSON( .. ) or $.ajax( .. ).
• 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)

Question: JQuery and MW.API

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)

Is the mwn information correct?

Information looks wrong. According to https://github.com/siddharthvp/mwn/releases/, the last version is from 2016 and not from 2023 or 2024. Some (outdated) dependencies have security issues, e.g. https://github.com/siddharthvp/mwn/issues/67 . — Preceding unsigned comment added by Torsknod (talk • contribs) 19:10, 31 October 2024 (UTC)

@Torsknod, I think you may be misreading data on https://github.com/siddharthvp/mwn/releases. The "Jun 16" information shown for the https://github.com/siddharthvp/mwn/releases/tag/2.0.3 release means 16 June 2024, not sometime in June 2016. See also https://www.npmjs.com/package/mwn?activeTab=versions. -- BDavis (WMF) (talk) 17:19, 1 November 2024 (UTC)

Thanks, seems I was too tired.

Unfortunately the topic with the outdated dependencies with security issues still remains. Torsknod (talk) 20:03, 3 November 2024 (UTC)

Java

Best Java libraries

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)

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

libmediawiki C++

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

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

PHP

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?

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)