resources/mediawiki.api/mediawiki.api.js

   1 /* mw.Api objects represent the API of a particular MediaWiki server. */
   2
   3 ( function( $, mw, undefined ) {
   4
   5         /**
   6          * @var defaultOptions {Object}
   7          * We allow people to omit these default parameters from API requests
   8          * there is very customizable error handling here, on a per-call basis
   9          * wondering, would it be simpler to make it easy to clone the api object,
  10          * change error handling, and use that instead?
  11          */
  12         var defaultOptions = {
  13
  14                         // Query parameters for API requests
  15                         parameters: {
  16                                 action: 'query',
  17                                 format: 'json'
  18                         },
  19
  20                         // Ajax options for jQuery.ajax()
  21                         ajax: {
  22                                 url: mw.util.wikiScript( 'api' ),
  23
  24                                 ok: function() {},
  25
  26                                 // caller can supply handlers for http transport error or api errors
  27                                 err: function( code, result ) {
  28                                         mw.log( 'mw.Api error: ' + code, 'debug' );
  29                                 },
  30
  31                                 timeout: 30000, // 30 seconds
  32
  33                                 dataType: 'json'
  34                         }
  35                 };
  36
  37         /**
  38          * Constructor to create an object to interact with the API of a particular MediaWiki server.
  39          *
  40          * @todo Share API objects with exact same config.
  41          * @example
  42          * <code>
  43          * var api = new mw.Api();
  44          * api.get( {
  45          *     action: 'query',
  46          *     meta: 'userinfo'
  47          * }, {
  48          *     ok: function () { console.log( arguments ); }
  49          * } );
  50          * </code>
  51          *
  52          * @constructor
  53          * @param options {Object} See defaultOptions documentation above. Ajax options can also be
  54          * overridden for each individual request to jQuery.ajax() later on.
  55          */
  56         mw.Api = function( options ) {
  57
  58                 if ( options === undefined ) {
  59                         options = {};
  60                 }
  61
  62                 // Force toString if we got a mw.Uri object
  63                 if ( options.ajax && options.ajax.url !== undefined ) {
  64                         options.ajax.url = String( options.ajax.url );
  65                 }
  66
  67                 options.parameters = $.extend( {}, defaultOptions.parameters, options.parameters );
  68                 options.ajax = $.extend( {}, defaultOptions.ajax, options.ajax );
  69
  70                 this.defaults = options;
  71         };
  72
  73         mw.Api.prototype = {
  74
  75                 /**
  76                  * For api queries, in simple cases the caller just passes a success callback.
  77                  * In complex cases they pass an object with a success property as callback and
  78                  * probably other options.
  79                  * Normalize the argument so that it's always the latter case.
  80                  *
  81                  * @param {Object|Function} An object contaning one or more of options.ajax,
  82                  * or just a success function (options.ajax.ok).
  83                  * @return {Object} Normalized ajax options.
  84                  */
  85                 normalizeAjaxOptions: function( arg ) {
  86                         var opt = arg;
  87                         if ( typeof arg === 'function' ) {
  88                                 opt = { 'ok': arg };
  89                         }
  90                         if ( !opt.ok ) {
  91                                 throw new Error( 'ajax options must include ok callback' );
  92                         }
  93                         return opt;
  94                 },
  95
  96                 /**
  97                  * Perform API get request
  98                  *
  99                  * @param {Object} request parameters
 100                  * @param {Object|Function} ajax options, or just a success function
 101                  * @return {jqXHR}
 102                  */
 103                 get: function( parameters, ajaxOptions ) {
 104                         ajaxOptions = this.normalizeAjaxOptions( ajaxOptions );
 105                         ajaxOptions.type = 'GET';
 106                         return this.ajax( parameters, ajaxOptions );
 107                 },
 108
 109                 /**
 110                  * Perform API post request
 111                  * @todo Post actions for nonlocal will need proxy
 112                  *
 113                  * @param {Object} request parameters
 114                  * @param {Object|Function} ajax options, or just a success function
 115                  * @return {jqXHR}
 116                  */
 117                 post: function( parameters, ajaxOptions ) {
 118                         ajaxOptions = this.normalizeAjaxOptions( ajaxOptions );
 119                         ajaxOptions.type = 'POST';
 120                         return this.ajax( parameters, ajaxOptions );
 121                 },
 122
 123                 /**
 124                  * Perform the API call.
 125                  *
 126                  * @param {Object} request parameters
 127                  * @param {Object} ajax options
 128                  * @return {jqXHR}
 129                  */
 130                 ajax: function( parameters, ajaxOptions ) {
 131                         var token;
 132                         parameters = $.extend( {}, this.defaults.parameters, parameters );
 133                         ajaxOptions = $.extend( {}, this.defaults.ajax, ajaxOptions );
 134
 135                         // Ensure that token parameter is last (per [[mw:API:Edit#Token]]).
 136                         if ( parameters.token ) {
 137                                 token = parameters.token;
 138                                 delete parameters.token;
 139                         }
 140                         // Some deployed MediaWiki >= 1.17 forbid periods in URLs, due to an IE XSS bug
 141                         // So let's escape them here. See bug #28235
 142                         // This works because jQuery accepts data as a query string or as an Object
 143                         ajaxOptions.data = $.param( parameters ).replace( /\./g, '%2E' );
 144                         // If we extracted a token parameter, add it back in.
 145                         if ( token ) {
 146                                 ajaxOptions.data += '&token=' + encodeURIComponent( token );
 147                         }
 148                         ajaxOptions.error = function( xhr, textStatus, exception ) {
 149                                 ajaxOptions.err( 'http', {
 150                                         xhr: xhr,
 151                                         textStatus: textStatus,
 152                                         exception: exception
 153                                 } );
 154                         };
 155
 156                         // Success just means 200 OK; also check for output and API errors
 157                         ajaxOptions.success = function( result ) {
 158                                 if ( result === undefined || result === null || result === '' ) {
 159                                         ajaxOptions.err( 'ok-but-empty',
 160                                                 'OK response but empty result (check HTTP headers?)' );
 161                                 } else if ( result.error ) {
 162                                         var code = result.error.code === undefined ? 'unknown' : result.error.code;
 163                                         ajaxOptions.err( code, result );
 164                                 } else {
 165                                         ajaxOptions.ok( result );
 166                                 }
 167                         };
 168
 169                         return $.ajax( ajaxOptions );
 170                 }
 171
 172         };
 173
 174         /**
 175          * @var {Array} List of errors we might receive from the API.
 176          * For now, this just documents our expectation that there should be similar messages
 177          * available.
 178          */
 179         mw.Api.errors = [
 180                 // occurs when POST aborted
 181                 // jQuery 1.4 can't distinguish abort or lost connection from 200 OK + empty result
 182                 'ok-but-empty',
 183
 184                 // timeout
 185                 'timeout',
 186
 187                 // really a warning, but we treat it like an error
 188                 'duplicate',
 189                 'duplicate-archive',
 190
 191                 // upload succeeded, but no image info.
 192                 // this is probably impossible, but might as well check for it
 193                 'noimageinfo',
 194                 // remote errors, defined in API
 195                 'uploaddisabled',
 196                 'nomodule',
 197                 'mustbeposted',
 198                 'badaccess-groups',
 199                 'stashfailed',
 200                 'missingresult',
 201                 'missingparam',
 202                 'invalid-file-key',
 203                 'copyuploaddisabled',
 204                 'mustbeloggedin',
 205                 'empty-file',
 206                 'file-too-large',
 207                 'filetype-missing',
 208                 'filetype-banned',
 209                 'filename-tooshort',
 210                 'illegal-filename',
 211                 'verification-error',
 212                 'hookaborted',
 213                 'unknown-error',
 214                 'internal-error',
 215                 'overwrite',
 216                 'badtoken',
 217                 'fetchfileerror',
 218                 'fileexists-shared-forbidden',
 219                 'invalidtitle',
 220                 'notloggedin'
 221         ];
 222
 223         /**
 224          * @var {Array} List of warnings we might receive from the API.
 225          * For now, this just documents our expectation that there should be similar messages
 226          * available.
 227          */
 228         mw.Api.warnings = [
 229                 'duplicate',
 230                 'exists'
 231         ];
 232
 233 })( jQuery, mediaWiki );