Extension:GlobalPreferences/API

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

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

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

Getting global preferences[edit]

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[edit]

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

Example[edit]

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[edit]

None.

Setting global preferences and local overrides[edit]

Token[edit]

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[edit]

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

Parameters[edit]

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[edit]

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[edit]

In addition to the usual stuff :

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