resources/src/mediawiki.ForeignApi/mediawiki.ForeignRest.core.js

   1 module.exports = ( function () {
   2
   3         /**
   4          * @classdesc Interact with the REST API of another MediaWiki site. mw.ForeignRest creates
   5          * an object like {@link mw.Rest}, but automatically handles everything required to communicate
   6          * with another MediaWiki wiki via cross-origin requests (CORS).
   7          *
   8          * The foreign wiki must be configured to accept requests from the current wiki. See
   9          * <https://www.mediawiki.org/wiki/Manual:$wgCrossSiteAJAXdomains> for details.
  10          * ```
  11          * const api = new mw.ForeignRest( 'https://commons.wikimedia.org/w/rest.php' );
  12          * api.get( '/page/Main_Page/html' )
  13          * .done( function ( data ) {
  14          *     console.log( data );
  15          * } );
  16          * ```
  17          *
  18          * Authentication-related MediaWiki extensions may extend this class to ensure that the user
  19          * authenticated on the current wiki will be automatically authenticated on the foreign one. These
  20          * extension modules should be registered using the ResourceLoaderForeignApiModules hook. See
  21          * CentralAuth for a practical example. The general pattern to extend and override the name is:
  22          * ```
  23          * function MyForeignRest() {};
  24          * OO.inheritClass( MyForeignRest, mw.ForeignRest );
  25          * mw.ForeignRest = MyForeignRest;
  26          * ```
  27          *
  28          * @class mw.ForeignRest
  29          * @extends mw.Rest
  30          * @since 1.36
  31          *
  32          * @constructor
  33          * @description Create an instance of `mw.ForeignRest`.
  34          * @param {string} url URL pointing to another wiki's `rest.php` endpoint.
  35          * @param {mw.ForeignApi} foreignActionApi
  36          * @param {Object} [options] See {@link mw.Rest}.
  37          * @param {boolean} [options.anonymous=false] Perform all requests anonymously. Use this option if
  38          *     the target wiki may otherwise not accept cross-origin requests, or if you don't need to
  39          *     perform write actions or read restricted information and want to avoid the overhead.
  40          *
  41          * @author Petr Pchelko
  42          */
  43         function CoreForeignRest( url, foreignActionApi, options ) {
  44                 this.apiUrl = url;
  45                 this.anonymous = options && options.anonymous;
  46                 this.foreignActionApi = foreignActionApi;
  47
  48                 options = $.extend( /* deep= */ true,
  49                         {
  50                                 ajax: {
  51                                         url: this.apiUrl,
  52                                         xhrFields: {
  53                                                 withCredentials: !this.anonymous
  54                                         }
  55                                 }
  56                         },
  57                         options
  58                 );
  59
  60                 // Call parent constructor
  61                 CoreForeignRest.super.call( this, options );
  62         }
  63
  64         OO.inheritClass( CoreForeignRest, mw.Rest );
  65
  66         return CoreForeignRest;
  67 }() );