summaryrefslogtreecommitdiff
path: root/resources/mediawiki.api/mediawiki.api.js
diff options
context:
space:
mode:
Diffstat (limited to 'resources/mediawiki.api/mediawiki.api.js')
-rw-r--r--resources/mediawiki.api/mediawiki.api.js322
1 files changed, 0 insertions, 322 deletions
diff --git a/resources/mediawiki.api/mediawiki.api.js b/resources/mediawiki.api/mediawiki.api.js
deleted file mode 100644
index cdc67679..00000000
--- a/resources/mediawiki.api/mediawiki.api.js
+++ /dev/null
@@ -1,322 +0,0 @@
-( function ( mw, $ ) {
-
- // We allow people to omit these default parameters from API requests
- // there is very customizable error handling here, on a per-call basis
- // wondering, would it be simpler to make it easy to clone the api object,
- // change error handling, and use that instead?
- var defaultOptions = {
-
- // Query parameters for API requests
- parameters: {
- action: 'query',
- format: 'json'
- },
-
- // Ajax options for jQuery.ajax()
- ajax: {
- url: mw.util.wikiScript( 'api' ),
-
- timeout: 30 * 1000, // 30 seconds
-
- dataType: 'json'
- }
- },
- tokenCache = {};
-
- /**
- * Constructor to create an object to interact with the API of a particular MediaWiki server.
- * mw.Api objects represent the API of a particular MediaWiki server.
- *
- * TODO: Share API objects with exact same config.
- *
- * var api = new mw.Api();
- * api.get( {
- * action: 'query',
- * meta: 'userinfo'
- * } ).done ( function ( data ) {
- * console.log( data );
- * } );
- *
- * @class
- *
- * @constructor
- * @param {Object} options See defaultOptions documentation above. Ajax options can also be
- * overridden for each individual request to {@link jQuery#ajax} later on.
- */
- mw.Api = function ( options ) {
-
- if ( options === undefined ) {
- options = {};
- }
-
- // Force toString if we got a mw.Uri object
- if ( options.ajax && options.ajax.url !== undefined ) {
- options.ajax.url = String( options.ajax.url );
- }
-
- options.parameters = $.extend( {}, defaultOptions.parameters, options.parameters );
- options.ajax = $.extend( {}, defaultOptions.ajax, options.ajax );
-
- this.defaults = options;
- };
-
- mw.Api.prototype = {
-
- /**
- * Normalize the ajax options for compatibility and/or convenience methods.
- *
- * @param {Object} [arg] An object contaning one or more of options.ajax.
- * @return {Object} Normalized ajax options.
- */
- normalizeAjaxOptions: function ( arg ) {
- // Arg argument is usually empty
- // (before MW 1.20 it was used to pass ok callbacks)
- var opts = arg || {};
- // Options can also be a success callback handler
- if ( typeof arg === 'function' ) {
- opts = { ok: arg };
- }
- return opts;
- },
-
- /**
- * Perform API get request
- *
- * @param {Object} parameters
- * @param {Object|Function} [ajaxOptions]
- * @return {jQuery.Promise}
- */
- get: function ( parameters, ajaxOptions ) {
- ajaxOptions = this.normalizeAjaxOptions( ajaxOptions );
- ajaxOptions.type = 'GET';
- return this.ajax( parameters, ajaxOptions );
- },
-
- /**
- * Perform API post request
- *
- * TODO: Post actions for non-local hostnames will need proxy.
- *
- * @param {Object} parameters
- * @param {Object|Function} [ajaxOptions]
- * @return {jQuery.Promise}
- */
- post: function ( parameters, ajaxOptions ) {
- ajaxOptions = this.normalizeAjaxOptions( ajaxOptions );
- ajaxOptions.type = 'POST';
- return this.ajax( parameters, ajaxOptions );
- },
-
- /**
- * Perform the API call.
- *
- * @param {Object} parameters
- * @param {Object} [ajaxOptions]
- * @return {jQuery.Promise} Done: API response data. Fail: Error code
- */
- ajax: function ( parameters, ajaxOptions ) {
- var token,
- apiDeferred = $.Deferred(),
- xhr;
-
- parameters = $.extend( {}, this.defaults.parameters, parameters );
- ajaxOptions = $.extend( {}, this.defaults.ajax, ajaxOptions );
-
- // Ensure that token parameter is last (per [[mw:API:Edit#Token]]).
- if ( parameters.token ) {
- token = parameters.token;
- delete parameters.token;
- }
- // Some deployed MediaWiki >= 1.17 forbid periods in URLs, due to an IE XSS bug
- // So let's escape them here. See bug #28235
- // This works because jQuery accepts data as a query string or as an Object
- ajaxOptions.data = $.param( parameters ).replace( /\./g, '%2E' );
-
- // If we extracted a token parameter, add it back in.
- if ( token ) {
- ajaxOptions.data += '&token=' + encodeURIComponent( token );
- }
-
- // Backwards compatibility: Before MediaWiki 1.20,
- // callbacks were done with the 'ok' and 'err' property in ajaxOptions.
- if ( ajaxOptions.ok ) {
- apiDeferred.done( ajaxOptions.ok );
- delete ajaxOptions.ok;
- }
- if ( ajaxOptions.err ) {
- apiDeferred.fail( ajaxOptions.err );
- delete ajaxOptions.err;
- }
-
- // Make the AJAX request
- xhr = $.ajax( ajaxOptions )
- // If AJAX fails, reject API call with error code 'http'
- // and details in second argument.
- .fail( function ( xhr, textStatus, exception ) {
- apiDeferred.reject( 'http', {
- xhr: xhr,
- textStatus: textStatus,
- exception: exception
- } );
- } )
- // AJAX success just means "200 OK" response, also check API error codes
- .done( function ( result ) {
- if ( result === undefined || result === null || result === '' ) {
- apiDeferred.reject( 'ok-but-empty',
- 'OK response but empty result (check HTTP headers?)'
- );
- } else if ( result.error ) {
- var code = result.error.code === undefined ? 'unknown' : result.error.code;
- apiDeferred.reject( code, result );
- } else {
- apiDeferred.resolve( result );
- }
- } );
-
- // Return the Promise
- return apiDeferred.promise( { abort: xhr.abort } ).fail( function ( code, details ) {
- mw.log( 'mw.Api error: ', code, details );
- } );
- },
-
- /**
- * Post to API with specified type of token. If we have no token, get one and try to post.
- * If we have a cached token try using that, and if it fails, blank out the
- * cached token and start over. For example to change an user option you could do:
- *
- * new mw.Api().postWithToken( 'options', {
- * action: 'options',
- * optionname: 'gender',
- * optionvalue: 'female'
- * } );
- *
- * @param {string} tokenType The name of the token, like options or edit.
- * @param {Object} params API parameters
- * @return {jQuery.Promise} See #post
- */
- postWithToken: function ( tokenType, params ) {
- var api = this, hasOwn = tokenCache.hasOwnProperty;
- if ( hasOwn.call( tokenCache, tokenType ) && tokenCache[tokenType] !== undefined ) {
- params.token = tokenCache[tokenType];
- return api.post( params ).then(
- null,
- function ( code ) {
- if ( code === 'badtoken' ) {
- // force a new token, clear any old one
- tokenCache[tokenType] = params.token = undefined;
- return api.post( params );
- }
- // Pass the promise forward, so the caller gets error codes
- return this;
- }
- );
- } else {
- return api.getToken( tokenType ).then( function ( token ) {
- tokenCache[tokenType] = params.token = token;
- return api.post( params );
- } );
- }
- },
-
- /**
- * Api helper to grab any token.
- *
- * @param {string} type Token type.
- * @return {jQuery.Promise}
- * @return {Function} return.done
- * @return {string} return.done.token Received token.
- */
- getToken: function ( type ) {
- var apiPromise,
- d = $.Deferred();
-
- apiPromise = this.get( {
- action: 'tokens',
- type: type
- }, {
- // Due to the API assuming we're logged out if we pass the callback-parameter,
- // we have to disable jQuery's callback system, and instead parse JSON string,
- // by setting 'jsonp' to false.
- // TODO: This concern seems genuine but no other module has it. Is it still
- // needed and/or should we pass this by default?
- } )
- .done( function ( data ) {
- // If token type is not available for this user,
- // key '...token' is missing or can contain Boolean false
- if ( data.tokens && data.tokens[type + 'token'] ) {
- d.resolve( data.tokens[type + 'token'] );
- } else {
- d.reject( 'token-missing', data );
- }
- } )
- .fail( d.reject );
-
- return d.promise( { abort: apiPromise.abort } );
- }
- };
-
- /**
- * @static
- * @property {Array}
- * List of errors we might receive from the API.
- * For now, this just documents our expectation that there should be similar messages
- * available.
- */
- mw.Api.errors = [
- // occurs when POST aborted
- // jQuery 1.4 can't distinguish abort or lost connection from 200 OK + empty result
- 'ok-but-empty',
-
- // timeout
- 'timeout',
-
- // really a warning, but we treat it like an error
- 'duplicate',
- 'duplicate-archive',
-
- // upload succeeded, but no image info.
- // this is probably impossible, but might as well check for it
- 'noimageinfo',
- // remote errors, defined in API
- 'uploaddisabled',
- 'nomodule',
- 'mustbeposted',
- 'badaccess-groups',
- 'stashfailed',
- 'missingresult',
- 'missingparam',
- 'invalid-file-key',
- 'copyuploaddisabled',
- 'mustbeloggedin',
- 'empty-file',
- 'file-too-large',
- 'filetype-missing',
- 'filetype-banned',
- 'filetype-banned-type',
- 'filename-tooshort',
- 'illegal-filename',
- 'verification-error',
- 'hookaborted',
- 'unknown-error',
- 'internal-error',
- 'overwrite',
- 'badtoken',
- 'fetchfileerror',
- 'fileexists-shared-forbidden',
- 'invalidtitle',
- 'notloggedin'
- ];
-
- /**
- * @static
- * @property {Array}
- * List of warnings we might receive from the API.
- * For now, this just documents our expectation that there should be similar messages
- * available.
- */
- mw.Api.warnings = [
- 'duplicate',
- 'exists'
- ];
-
-}( mediaWiki, jQuery ) );