MediaWiki API

A library for interacting with MediaWiki API from Ruby. Uses adapter-agnostic Faraday gem to talk to the API.

Add this line to your application's Gemfile:

gem "mediawiki_api"

And then execute:

$ bundle

Or install it yourself as:

$ gem install mediawiki_api

Assuming you have MediaWiki installed via MediaWiki-Vagrant.

require "mediawiki_api"

client = MediawikiApi::Client.new "http://127.0.0.1:8080/w/api.php"
client.log_in "username", "password" # default Vagrant username and password are "Admin", "vagrant"
client.set_oauth_access_token("user_oauth_token") # INSTEAD of logging in, will make all actions as the user authenticated via OAuth
client.create_account "username", "password" # will not work on wikis that require CAPTCHA, like Wikipedia
client.create_page "title", "content"
client.get_wikitext "title"
client.protect_page "title", "reason", "protections" #  protections are optional, default is "edit=sysop|move=sysop"
client.delete_page "title", "reason"
client.upload_image "filename", "path", "comment", "ignorewarnings"
client.watch_page "title"
client.unwatch_page "title"
client.meta :siteinfo, siprop: "extensions"
client.prop :info, titles: "Some page"
client.query titles: ["Some page", "Some other page"]

Any API action can be requested using #action. See the MediaWiki API documentation for supported actions and parameters.

By default, the client will attempt to get a csrf token before attempting the action. For actions that do not require a token, you can specify token_type: false to avoid requesting the unnecessary token before the real request. For example:

client.action :parse, page: 'Main Page', token_type: false

MediaWiki API gem at: Gerrit, GitHub, RubyGems, Code Climate.

See https://www.mediawiki.org/wiki/Gerrit

• Add oauth_access_token, allowing authenticated actions on behalf of users via Wikimedia's OAuth service. Obtaining the access token is up to this gem's user. In Ruby, one can use the [oauth2](https://gitlab.com/oauth-xx/oauth2/) gem. A working example can be seen in the source code of the Luthor tool.
• New maintainer: @abartov

• Add text param to MediawikiApi::Client#upload_image

• Automatically follow redirects for all API requests.

• Update account creation code for AuthManager. This change updates the gem to test which API flavor is in use, then send requests accordingly.

• Client cookies can now be read and modified via MediawikiApi::Client#cookies.
• Logging in will recurse upon a NeedToken API error only once to avoid infinite recursion in cases where authentication is repeatedly unsuccessful.

• Allow for response-less ApiError exceptions to make mocking in tests easier

• Use action=query&meta=tokens to fetch tokens, instead of deprecated action=tokens

• Actions now automatically refresh token and re-submit action if first attempt returns 'badtoken'.

• HTTP 400 and 500 responses now result in an HttpError exception.
• Edit failures now result in an EditError exception.

• Fix error handling for token requests

• Automatic response parsing.
• Handling of API error responses.
• Watch/unwatch support.
• Query support.
• Public MediawikiApi::Client#action method for advanced API use.

• Added MediawikiApi::Client#protect_page.
• Updated documentation.

• Added MediawikiApi::Client#upload_image.

• Added MediawikiApi::Client#get_wikitext.

• Updated documentation.

• Complete refactoring.
• Removed MediawikiApi#create_article, #create_user and #delete_article.
• Added MediawikiApi::Client#new, #log_in, #create_page, #delete_page, #create_account.
• Added unit tests.

• Added MediawikiApi#delete_article.

• Added MediawikiApi#create_article and #create_user.

© Copyright 2013-2023, Wikimedia Foundation & Contributors. Released under the terms of the GNU General Public License, version 2 or later.