API:Options

From MediaWiki.org
Jump to navigation Jump to search
Other languages:Project:Language policy English  • 日本語
This page is part of the MediaWiki action API documentation.


MediaWiki action API

v · d · e
Options
Change options
This module cannot be used as a GeneratorAPI:generator.
Prefix
Required rights none
Post only? No
Generated help Current
Version added
≥ 1.20

Token[edit]

To change options, an options token is required.

MediaWiki version: ≥ 1.24

Options tokens can be obtained via action=query&meta=tokens

Obtaining an options token

api.php?action=query&meta=tokens [try in ApiSandbox]
Result 
{
    "query": {
        "tokens": {
            "csrftoken": "f38d52ee5c9b49ce17f5e55c48bb1166547cbc71+\\"
        }
    }
}


MediaWiki versions: 1.20 – 1.24

In older versions, a token can be obtained via action=tokens&type=options:

Obtaining an options token

api.php?action=tokens&type=options [try in ApiSandbox]
Result 
<?xml version="1.0" encoding="utf-8"?>
<api>
  <tokens optionstoken="58b54e0bab4a1d3fd3f7653af38e75cb+\" />
</api>

Changing options[edit]

Options can be changed using action=options.

While this API is primarily intended for changing options which are registered by MediaWiki core or extensions and available on Special:Preferences, since Gerrit #I5f9ba5 you can also use it to set arbitrary user options that can be used by user-scripts or external editors.

userjs options must begin with the prefix userjs-.

The following limits apply to all user options:

  • The length of the key must not be more than 255 bytes
  • The key must consist only of ASCII letters, numbers, hyphens and underscores (a-z, A-Z, 0-9, _, -)
  • The byte length (not character length) of the value must be <= 65535. However, please minimize the length used (both per-option and total), because user options are downloaded in their entirety for every page view. Only very small datums should be stored.

There are currently no limit on the number of user options you can set at once. You can store a tree of data within a user option by encoding it as a JSON string.

Parameters[edit]

  • reset: Resets all preferences to the site defaults.
  • resetkinds: List of types of options to reset when the reset option is set. (Default: all) 1.21+
  • change: Pipe-separated list of changes, formatted name=value (e.g. skin=vector), value cannot contain pipe characters.
Note: Providing only names of options without equal sign (e.g. hideminor|skin) results in resetting them. In the case of an arbitrary userjs- name/value pair, the resetting results in the removal of the name/value pair; in other words - deletion.
  • optionname: A name of a option which should have an optionvalue set.
  • optionvalue: A value of the option specified by the optionname, can contain pipe characters.
  • token: A "csrf" token retrieved from action=query&meta=tokens

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 (for example, a user signature) use an optionname & optionvalue pair.

Available Options[edit]

The following is an example list obtained with /w/api.php?action=query&format=json&meta=userinfo&uiprop=options for a Wikipedia (MW 1.24) account.

Note that most of the options listed here are defined by various MediaWiki extensions, like Echo, VisualEditor, WikiLove, Gadgets or EducationProgram, among others.

  • ccmeonemails: 0
  • cols: 80
  • date: "mdy"
  • diffonly: 0
  • disablemail: 0
  • editfont: "default"
  • editondblclick: 0
  • editsectiononrightclick: 0
  • enotifminoredits: 0
  • enotifrevealaddr: 0
  • enotifusertalkpages: 1
  • enotifwatchlistpages: 0
  • extendwatchlist: "1"
  • fancysig: "1"
  • forceeditsummary: "1"
  • gender: "male"
  • hideminor: 0
  • hidepatrolled: 0
  • imagesize: 2
  • math: 0
  • minordefault: 0
  • newpageshidepatrolled: 0
  • nickname: user signature
  • norollbackdiff: 0
  • numberheadings: 0
  • previewonfirst: 0
  • previewontop: 1
  • rcdays: "14"
  • rclimit: "100"
  • rows: 25
  • showhiddencats: false
  • shownumberswatching: 1
  • showtoolbar: 1
  • skin: "vector"
  • stubthreshold: 0
  • thumbsize: "3"
  • underline: 2
  • uselivepreview: 0
  • usenewrc: 0
  • watchcreations: 1
  • watchdefault: "1"
  • watchdeletion: 0
  • watchlistdays: "2"
  • watchlisthideanons: 0
  • watchlisthidebots: 0
  • watchlisthideliu: 0
  • watchlisthideminor: 0
  • watchlisthideown: 0
  • watchlisthidepatrolled: 0
  • watchmoves: "1"
  • wllimit: "300"
  • useeditwarning: 1
  • prefershttps: 1
  • flaggedrevssimpleui: 1
  • flaggedrevsstable: 0
  • flaggedrevseditdiffs: true
  • flaggedrevsviewdiffs: false
  • usebetatoolbar: 1
  • usebetatoolbar-cgd: 1
  • multimediaviewer-enable: true
  • visualeditor-enable: 0
  • visualeditor-betatempdisable: 0
  • visualeditor-enable-experimental: 0
  • visualeditor-enable-language: 0
  • visualeditor-hidebetawelcome: 0
  • wikilove-enabled: 1
  • mathJax: false
  • echo-subscriptions-web-page-review: true
  • echo-subscriptions-email-page-review: false
  • ep_showtoplink: false
  • ep_bulkdelorgs: false
  • ep_bulkdelcourses: true
  • ep_showdyk: true
  • echo-subscriptions-web-education-program: true
  • echo-subscriptions-email-education-program: false
  • echo-notify-show-link: true
  • echo-show-alert: true
  • echo-email-frequency: 0
  • echo-email-format: "html"
  • echo-subscriptions-email-system: true
  • echo-subscriptions-web-system: true
  • echo-subscriptions-email-user-rights: true
  • echo-subscriptions-web-user-rights: true
  • echo-subscriptions-email-other: false
  • echo-subscriptions-web-other: true
  • echo-subscriptions-email-edit-user-talk: 1
  • echo-subscriptions-web-edit-user-talk: true
  • echo-subscriptions-email-reverted: false
  • echo-subscriptions-web-reverted: true
  • echo-subscriptions-email-article-linked: false
  • echo-subscriptions-web-article-linked: false
  • echo-subscriptions-email-mention: false
  • echo-subscriptions-web-mention: true
  • echo-subscriptions-web-edit-thank: true
  • echo-subscriptions-email-edit-thank: false
  • echo-subscriptions-web-flow-discussion: true
  • echo-subscriptions-email-flow-discussion: false
  • gettingstarted-task-toolbar-show-intro: true
  • uls-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: true
  • searchNs1: false
  • searchNs2: "1"
  • searchNs3: false
  • searchNs4: "1"
  • searchNs5: false
  • searchNs6: "1"
  • searchNs7: false
  • searchNs8: "1"
  • searchNs9: false
  • searchNs10: "1"
  • searchNs11: false
  • searchNs12: "1"
  • searchNs13: false
  • searchNs14: "1"
  • searchNs15: false
  • searchNs100: false
  • searchNs101: false
  • searchNs108: false
  • searchNs109: false
  • searchNs118: false
  • searchNs119: false
  • searchNs446: false
  • searchNs447: false
  • searchNs710: false
  • searchNs711: false
  • searchNs828: false
  • searchNs829: false
  • gadget-teahouse: ""
  • gadget-ReferenceTooltips: 1
  • gadget-DRN-wizard: 1
  • gadget-charinsert: 1
  • gadget-refToolbar: 1
  • gadget-mySandbox: 1
  • betafeatures-vector-compact-personal-bar: "0"
  • cirrussearch-default: "0"
  • pagetriage-lastuse: timestamp
  • popups: "0"
  • timecorrection: "ZoneInfo|60|Europe/London"
  • uls-compact-links: "0"
  • usecodeeditor: "1"
  • userjs-arbitraryKeyName: arbitrary value
  • watchlisttoken: token

Example[edit]

Note: In this example, all parameters are passed in a GET request for the sake of simplicity. However, action=options requires POST requests; GET requests will cause an error. Changing a single option

api.php?action=options&token=58b54e0bab4a1d3fd3f7653af38e75cb%2B\&change=hideminor=1 [try in ApiSandbox]
Result 
<?xml version="1.0" encoding="utf-8"?>
<api options="success" />

Resetting all options and changing a single option

api.php?action=options&token=58b54e0bab4a1d3fd3f7653af38e75cb%2B\&reset&change=hideminor=1 [try in ApiSandbox]
Result 
<?xml version="1.0" encoding="utf-8"?>
<api options="success" />

Changing three options

api.php?action=options&token=58b54e0bab4a1d3fd3f7653af38e75cb%2B\&change=hideminor=1|skin=vector&optionname=nickname&optionvalue=custom-signa|ture [try in ApiSandbox]
Result 
<?xml version="1.0" encoding="utf-8"?>
<api options="success" />

Possible errors[edit]

In addition to the usual stuff:

Code Info
notloggedin Anonymous users cannot change preferences
nochanges No changes were requested

See also[edit]

Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Options&oldid=2735261"