API:Options
This page is part of the MediaWiki Action API documentation. |
MediaWiki version: | ≥ 1.20 |
POST request to change preferences of the current user.
API documentation[edit]
action=options(main | options)
Change preferences of the current user. Only options which are registered in core or in one of installed extensions, or options with keys prefixed with Parameters:
Examples:
|
Example[edit]
Making any POST request is a multi-step process:
- Log in, via one of the methods described on API:Login .
- Get an Edit token .
- Send a POST request, with the CSRF token, to take action on a page.
The sample code below covers the final step in detail.
POST request[edit]
Changing three options
Result |
---|
<?xml version="1.0" encoding="utf-8"?>
<api options="success" />
|
Response[edit]
{
"options": "success"
}
Sample code[edit]
Python[edit]
#!/usr/bin/python3
"""
change_user_options.py
MediaWiki API Demos
Demo of `Options` module: POST request to change three options
for current user
MIT license
"""
import requests
S = requests.Session()
URL = "https://test.wikipedia.org/w/api.php"
# Step 1: GET request to fetch login token
PARAMS_0 = {
"action": "query",
"meta": "tokens",
"type": "login",
"format": "json"
}
R = S.get(url=URL, params=PARAMS_0)
DATA = R.json()
LOGIN_TOKEN = DATA['query']['tokens']['logintoken']
# Step 2: POST request to log in. Use of main account for login is not
# supported. Obtain credentials via Special:BotPasswords
# (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
PARAMS_1 = {
"action": "login",
"lgname": "bot_user_name",
"lgpassword": "bot_password",
"lgtoken": LOGIN_TOKEN,
"format": "json"
}
R = S.post(URL, data=PARAMS_1)
# Step 3: GET request to fetch CSRF token
PARAMS_2 = {
"action": "query",
"meta": "tokens",
"format": "json"
}
R = S.get(url=URL, params=PARAMS_2)
DATA = R.json()
CSRF_TOKEN = DATA['query']['tokens']['csrftoken']
# Step 4: POST request to change user options
# You can check out the large list of options you can change
# at https://www.mediawiki.org/wiki/API:Options
PARAMS_3 = {
"action": "options",
"format": "json",
"token": CSRF_TOKEN,
"change": "language=en|skin=vector",
"optionname": "nickname",
"optionvalue": "custom-signa|ture"
}
R = S.post(URL, data=PARAMS_3)
DATA = R.json()
print(DATA)
PHP[edit]
<?php
/*
change_user_options.php
MediaWiki API Demos
Demo of `Options` module: POST request to change three options
for current user
MIT license
*/
$endPoint = "https://test.wikipedia.org/w/api.php";
$login_Token = getLoginToken(); // Step 1
loginRequest( $login_Token ); // Step 2
$csrf_Token = getCSRFToken(); // Step 3
change_options( $csrf_Token ); // Step 4
// Step 1: GET request to fetch login token
function getLoginToken() {
global $endPoint;
$params1 = [
"action" => "query",
"meta" => "tokens",
"type" => "login",
"format" => "json"
];
$url = $endPoint . "?" . http_build_query( $params1 );
$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
$result = json_decode( $output, true );
return $result["query"]["tokens"]["logintoken"];
}
// Step 2: POST request to log in. Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest( $logintoken ) {
global $endPoint;
$params2 = [
"action" => "login",
"lgname" => "bot_user_name",
"lgpassword" => "bot_password",
"lgtoken" => $logintoken,
"format" => "json"
];
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $endPoint );
curl_setopt( $ch, CURLOPT_POST, true );
curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params2 ) );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
}
// Step 3: GET request to fetch CSRF token
function getCSRFToken() {
global $endPoint;
$params3 = [
"action" => "query",
"meta" => "tokens",
"format" => "json"
];
$url = $endPoint . "?" . http_build_query( $params3 );
$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
$result = json_decode( $output, true );
return $result["query"]["tokens"]["csrftoken"];
}
// Step 4: POST request to edit a page
function change_options( $csrftoken ) {
global $endPoint;
$params4 = [
"action" => "options",
"change" => "language=en|skin=timeless",
"optionname" => "nickname",
"optionvalue" => "custom-signa|ture",
"token" => $csrftoken,
"format" => "json"
];
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $endPoint );
curl_setopt( $ch, CURLOPT_POST, true );
curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params4 ) );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
echo ( $output );
}
JavaScript[edit]
/*
change_user_options.js
MediaWiki API Demos
Demo of `Options` module: POST request to change two options
for current user
MIT license
*/
var request = require('request').defaults({jar: true}),
url = "https://test.wikipedia.org/w/api.php";
// Step 1: GET request to fetch login token
function getLoginToken() {
var params_0 = {
action: "query",
meta: "tokens",
type: "login",
format: "json"
};
request.get({ url: url, qs: params_0 }, function (error, res, body) {
if (error) {
return;
}
var data = JSON.parse(body);
loginRequest(data.query.tokens.logintoken);
});
}
// Step 2: POST request to log in.
// Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest(login_token) {
var params_1 = {
action: "login",
lgname: "bot_username",
lgpassword: "bot_password",
lgtoken: login_token,
format: "json"
};
request.post({ url: url, form: params_1 }, function (error, res, body) {
if (error) {
return;
}
getCsrfToken();
});
}
// Step 3: GET request to fetch CSRF token
function getCsrfToken() {
var params_2 = {
action: "query",
meta: "tokens",
format: "json"
};
request.get({ url: url, qs: params_2 }, function(error, res, body) {
if (error) {
return;
}
var data = JSON.parse(body);
change_options(data.query.tokens.csrftoken);
});
}
// Step 4: POST request to change the user options
function change_options(csrf_token) {
var params_3 = {
action: "options",
change: "language=en|skin=timeless",
token: csrf_token,
format: "json"
};
request.post({ url: url, form: params_3 }, function (error, res, body) {
if (error) {
return;
}
console.log(body);
});
}
// Start From Step 1
getLoginToken();
MediaWiki JS[edit]
/*
change_user_options.js
MediaWiki API Demos
Demo of `Options` module: POST request to change three options
for current user
MIT License
*/
var params = {
action: 'options',
change: 'language=en|skin=monobook',
optionname: 'nickname',
optionvalue: 'custom-signa|ture',
format: 'json'
},
api = new mw.Api();
api.postWithToken( 'csrf', params ).done( function ( data ) {
console.log( data );
} );
Available Options[edit]
/w/api.php?action=query&format=json&meta=userinfo&uiprop=options
for a Wikipedia (MW 1.24) account. Most of the options listed here are defined by various MediaWiki extensions, like Echo , VisualEditor , WikiLove , Gadgets or EducationProgram , among others.ccmeonemails
: 0cols
: 80date
: "mdy"diffonly
: 0disablemail
: 0editfont
: "default"editondblclick
: 0editsectiononrightclick
: 0enotifminoredits
: 0enotifrevealaddr
: 0enotifusertalkpages
: 1enotifwatchlistpages
: 0extendwatchlist
: "1"fancysig
: "1"forceeditsummary
: "1"gender
: "male"hideminor
: 0hidepatrolled
: 0imagesize
: 2math
: 0minordefault
: 0newpageshidepatrolled
: 0nickname
: user signaturenorollbackdiff
: 0numberheadings
: 0previewonfirst
: 0previewontop
: 1rcdays
: "14"rclimit
: "100"rows
: 25showhiddencats
: falseshownumberswatching
: 1showtoolbar
: 1skin
: "vector"stubthreshold
: 0thumbsize
: "3"underline
: 2uselivepreview
: 0usenewrc
: 0watchcreations
: 1watchdefault
: "1"watchdeletion
: 0watchlistdays
: "2"watchlisthideanons
: 0watchlisthidebots
: 0watchlisthideliu
: 0watchlisthideminor
: 0watchlisthideown
: 0watchlisthidepatrolled
: 0watchmoves
: "1"wllimit
: "300"useeditwarning
: 1prefershttps
: 1flaggedrevssimpleui
: 1flaggedrevsstable
: 0flaggedrevseditdiffs
: trueflaggedrevsviewdiffs
: falseusebetatoolbar
: 1usebetatoolbar-cgd
: 1multimediaviewer-enable
: truevisualeditor-enable
: 0visualeditor-betatempdisable
: 0visualeditor-enable-experimental
: 0visualeditor-enable-language
: 0visualeditor-hidebetawelcome
: 0wikilove-enabled
: 1mathJax
: falseecho-subscriptions-web-page-review
: trueecho-subscriptions-email-page-review
: falseep_showtoplink
: falseep_bulkdelorgs
: falseep_bulkdelcourses
: trueep_showdyk
: trueecho-subscriptions-web-education-program
: trueecho-subscriptions-email-education-program
: falseecho-notify-show-link
: trueecho-show-alert
: trueecho-email-frequency
: 0echo-email-format
: "html"echo-subscriptions-email-system
: trueecho-subscriptions-web-system
: trueecho-subscriptions-email-user-rights
: trueecho-subscriptions-web-user-rights
: trueecho-subscriptions-email-other
: falseecho-subscriptions-web-other
: trueecho-subscriptions-email-edit-user-talk
: 1echo-subscriptions-web-edit-user-talk
: trueecho-subscriptions-email-reverted
: falseecho-subscriptions-web-reverted
: trueecho-subscriptions-email-article-linked
: falseecho-subscriptions-web-article-linked
: falseecho-subscriptions-email-mention
: falseecho-subscriptions-web-mention
: trueecho-subscriptions-web-edit-thank
: trueecho-subscriptions-email-edit-thank
: falseecho-subscriptions-web-flow-discussion
: trueecho-subscriptions-email-flow-discussion
: falsegettingstarted-task-toolbar-show-intro
: trueuls-preferences
: ""language
: "en"variant-gan
: "gan"variant-iu
: "iu"variant-kk
: "kk"variant-ku
: "ku"variant-shi
: "shi"variant-sr
: "sr"variant-tg
: "tg"variant-uz
: "uz"variant-zh
: "zh"searchNs0
: truesearchNs1
: falsesearchNs2
: "1"searchNs3
: falsesearchNs4
: "1"searchNs5
: falsesearchNs6
: "1"searchNs7
: falsesearchNs8
: "1"searchNs9
: falsesearchNs10
: "1"searchNs11
: falsesearchNs12
: "1"searchNs13
: falsesearchNs14
: "1"searchNs15
: falsesearchNs100
: falsesearchNs101
: falsesearchNs108
: falsesearchNs109
: falsesearchNs118
: falsesearchNs119
: falsesearchNs446
: falsesearchNs447
: falsesearchNs710
: falsesearchNs711
: falsesearchNs828
: falsesearchNs829
: falsegadget-teahouse
: ""gadget-ReferenceTooltips
: 1gadget-DRN-wizard
: 1gadget-charinsert
: 1gadget-refToolbar
: 1gadget-mySandbox
: 1betafeatures-vector-compact-personal-bar
: "0"cirrussearch-default
: "0"pagetriage-lastuse
: timestamppopups
: "0"timecorrection
: "ZoneInfo|60|Europe/London"uls-compact-links
: "0"usecodeeditor
: "1"userjs-arbitraryKeyName
: arbitrary valuewatchlisttoken
: token
Possible errors[edit]
In addition to the usual stuff :
Code | Info |
---|---|
notloggedin | Anonymous users cannot change preferences |
nochanges | No changes were requested. |
Parameter history[edit]
- 1.21: Introduced
resetkinds
Additional notes[edit]
- This API is primarily intended for changing options which are registered by MediaWiki core or extensions and available on Special:Preferences.
- You can also use the API to set arbitrary user options that can be used by user scripts or external editors. These options must begin with the prefix
userjs-
. - There are currently no limit on the number of user options you can set at once. You can store data within a user option by encoding it as a
JSON
string. - Providing only names of options without equal sign results in resetting them (e.g.
hideminor|skin
). In the case of an arbitraryuserjs-
key/value pair, the resetting results in its deletion. - The
change
parameter cannot be used to set a value which contains a pipe character|
, as it is used by the API to separate options. If you need to set such a value (e.g., a user signature) use anoptionname
&optionvalue
pair. - The following limits apply to all user options:
- The byte length of the key must be <= 255.
- The byte length of the value must be <= 65535.
- The key must consist only of ASCII letters, numbers, hyphens and underscores (a-z, A-Z, 0-9, _, -).
See also[edit]
- API:Userinfo - for reading existing options.