Extension:GlobalPreferences/API

Getting global preferences

globalpreferences
Get global preferences and local overrides for the current user. This module cannot be used as a generator.
Prefix	gpr
Required rights	editmyoptions
Post only?	No
Generated help	Current

If only the effective preferences for a user are required, the usual meta=userinfo&uiprop=options can be used, however if you need to know where is every preference value coming from, you will need to use this API.

Parameters

• gprprop: Which preferences to get (Default: preferences|localoverrides)
  • preferences: Global preferences
  • localoverrides: Local overrides

Example

Getting global preferences

api.php?action=query&meta=globalpreferences [try in ApiSandbox]

Result
{ "batchcomplete": "", "query": { "globalpreferences": { "preferences": { "advancedsearch": "1", "ccmeonemails": "1", "disablemail": "0", "email-allow-new-users": 1 }, "localoverrides": { "ccmeonemails": 0, "email-allow-new-users": 0 } } } }

Possible errors

None.

Setting global preferences and local overrides

globalpreferences Change global preferences This module cannot be used as a generator. Prefix Required rights none Post only? No Generated help Current

globalpreferenceoverrides Change local preference overrides This module cannot be used as a generator. Prefix Required rights none Post only? No Generated help Current

Token

To change options, a CSRF token is required.

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

Obtaining a token

api.php?action=query&meta=tokens [try in ApiSandbox]

Result
{ "query": { "tokens": { "csrftoken": "f38d52ee5c9b49ce17f5e55c48bb1166547cbc71+\\" } } }

Changing options

GlobalPreferences provides two modules to change preferences, action=globalpreferences and action=globalpreferenceoverrides. They work exactly like action=options and have the same parameters.

Parameters

• reset: Resets all preferences.
  • Resetting a global preference means it will not be global anymore while resetting a local override means that the global preference will be used.
• resetkinds: List of types of preferences to reset when the reset parameter is set. (Default: all)
• change: Pipe-separated list of changes, formatted name=value (e.g. skin=vector), value cannot contain pipe characters.

Tracked in Phabricator
Task T207448

Note: Providing only names of preferences without equal sign (e.g. hideminor|skin) results in resetting them. In the case of an arbitrary userjs- name/value pair, the resetting should result in the removal of the name/value pair—except it doesn't currently.

• optionname: A name of a preference which should have an optionvalue set.
• optionvalue: A value of the preference 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.

Example

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

api.php?action=globalpreferences&token=58b54e0bab4a1d3fd3f7653af38e75cb%2B\&change=hideminor=1 [try in ApiSandbox]

Result
{ "globalpreferences": "success" }

Resetting all preferences and then setting a single one

api.php?action=globalpreferences&token=58b54e0bab4a1d3fd3f7653af38e75cb%2B\&reset&change=hideminor=1 [try in ApiSandbox]

Result
{ "globalpreferences": "success" }

Changing three preferences

api.php?action=globalpreferenceoverrides&token=58b54e0bab4a1d3fd3f7653af38e75cb%2B\&change=hideminor=1|skin=vector&optionname=nickname&optionvalue=custom-signa|ture [try in ApiSandbox]

Result
{ "globalpreferenceoverrides": "success" }

Possible errors

In addition to the usual stuff :

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