Manual:CORS/pl
The MediaWiki API supports CORS (cross-origin resource sharing) requests if $wgCrossSiteAJAXdomains is enabled.
This is used on Wikimedia sites to do things like allow image uploads directly to Commons from Wikipedia sites on the mobile interface.
This page details how to use CORS requests in your JavaScript code to communicate between wikis on different domains.
Description
For CORS requests to go through, you need to pass an origin parameter in the query string with the local wiki protocol+host as value (for example, https://www.mediawiki.org).
This must match one of the values in $wgCrossSiteAJAXdomains on the foreign wiki.
If you wish the browser to use any cookies it might have for the domain, to keep the current user logged in, you also need to set the withCredentials field of XMLHttpRequest to true.
For anonymous requests, origin query string parameter can be set to * which will allow requests from anywhere.
Przykłady
In the examples below, we assume that the local wiki from which the requests originate is www.mediawiki.org, and that the foreign wiki which the requests target is en.wikipedia.org.
Using mediawiki.ForeignApi
| Wersja MediaWiki: | ≥ 1.26 |
The mediawiki.ForeignApi module is an extension of mediawiki.api which automatically handles the details for you.
See the code-level documentation.
An example that checks whether the user is logged in on the foreign wiki:
await mw.loader.using( 'mediawiki.ForeignApi' )
const api = new mw.ForeignApi( 'https://en.wikipedia.org/w/api.php' );
const data = await api.get( { action: 'query', meta: 'userinfo' } );
alert( `Foreign user ${data.query.userinfo.name} (ID ${data.query.userinfo.id})` );
A basic write API example. We're acquiring a csrf token and using it to set a persistent custom user preference that a gadget might use afterwards:
await mw.loader.using( 'mediawiki.ForeignApi' );
const api = new mw.ForeignApi( 'https://en.wikipedia.org/w/api.php' );
const data = await api.get( { action: 'query', meta: 'tokens' } );
await api.post( {
action: 'options',
token: data.query.tokens.csrftoken,
optionname: 'userjs-test',
optionvalue: 'Hello world!'
} );
The same example can be rewritten more succinctly using some mediawiki.api helper methods, which are available for ForeignApi too:
await mw.loader.using( 'mediawiki.ForeignApi' );
const api = new mw.ForeignApi( 'https://en.wikipedia.org/w/api.php' );
await api.postWithToken( 'options', {
action: 'options',
optionname: 'userjs-test',
optionvalue: 'Hello world!'
} );
An example that uses the REST API:
var api = new mw.ForeignRest( 'https://commons.wikimedia.org/w/rest.php' );
await api.get( '/page/Main_Page/html' );
Anonymous requests
If the target wiki does not accept cross-origin requests, or if you don't need to perform write actions or read restricted information and want to avoid the overhead, you may set the anonymous option of the mediawiki.ForeignApi constructor:
await mw.loader.using( 'mediawiki.ForeignApi' )
const api = new mw.ForeignApi( 'https://en.wikipedia.org/w/api.php', { anonymous: true } );
...
Using mw.ForeignRest
The equivalent to be used for the REST API is mw.ForeignRest. For example, to log data from Wikimedia Commons:
var value = "Test";
var actionApi = new mw.ForeignApi( 'https://commons.wikimedia.org/w/api.php' );
const api = new mw.ForeignRest(
'https://commons.wikimedia.org/w/rest.php/v1',
actionApi,
{ anonymous: true }
);
api.get( '/search/title', {
limit: '10',
q: `${ encodeURIComponent( value ) }`,
origin: '*'
} )
.done( function ( data ) {
console.log( data );
} );
Using jQuery methods
If you do not wish to use mediawiki.api for whatever reason, or if you're curious how this works at a lower level, here's how to implement the same functionality using plain jQuery AJAX functionality. You could even use plain XMLHttpRequest.
An example that checks whether the user is logged in on the foreign wiki:
const { query } = await $.ajax( {
url: 'https://en.wikipedia.org/w/api.php',
data: {
action: 'query',
meta: 'userinfo',
format: 'json',
origin: 'https://www.mediawiki.org'
},
xhrFields: {
withCredentials: true
},
dataType: 'json'
} );
alert( `Foreign user ${query.userinfo.name} (ID ${query.userinfo.id})` );
A basic write API example:
const { query } = await $.ajax( {
url: 'https://en.wikipedia.org/w/api.php',
data: {
action: 'query',
meta: 'tokens',
format: 'json',
origin: 'https://www.mediawiki.org'
},
xhrFields: {
withCredentials: true
},
dataType: 'json'
} );
await $.ajax( {
url: 'https://en.wikipedia.org/w/api.php?origin=https://www.mediawiki.org',
method: 'POST',
data: {
action: 'options',
format: 'json',
token: query.tokens.csrftoken,
optionname: 'userjs-test',
optionvalue: 'Hello world!'
},
xhrFields: {
withCredentials: true
},
dataType: 'json'
} );
Note that origin is part of the URL since POST CORS requests are preflighted and the origin parameter must be included in the preflight request.
Extensions to the mechanism
CentralAuth
| Wersja MediaWiki: | ≥ 1.26 |
CentralAuth allows your code to authenticate on the foreign wiki as the user currently logged in on the local wiki using a centralauthtoken. This guarantees that the same associated account will be used for actions on both wikis, unlike regular CORS (which requires the user to have previously logged in to the foreign wiki).
If both the local and foreign wiki have CentralAuth installed, the mediawiki.ForeignApi mechanism is seamlessly extended to handle this for you. If you're implementing it yourself, see centralauthtoken for instructions on how to acquire a token (from the local wiki) and pass it to a request (to the foreign wiki).
Alternatives
For anonymous requests you can use the JSONP format instead. This is simpler but slightly less secure (it fetches and executes arbitrary JavaScript code from the wiki so an attacker who took over the MediaWiki site has an XSS vector against the remote site).