3 // We allow people to omit these default parameters from API requests
4 // there is very customizable error handling here, on a per-call basis
5 // wondering, would it be simpler to make it easy to clone the api object,
6 // change error handling, and use that instead?
9 // Query parameters for API requests
15 // Ajax options for jQuery.ajax()
17 url: mw.util.wikiScript( 'api' ),
19 timeout: 30 * 1000, // 30 seconds
27 * Constructor to create an object to interact with the API of a particular MediaWiki server.
28 * mw.Api objects represent the API of a particular MediaWiki server.
30 * TODO: Share API objects with exact same config.
32 * var api = new mw.Api();
36 * } ).done ( function ( data ) {
37 * console.log( data );
43 * @param {Object} options See defaultOptions documentation above. Ajax options can also be
44 * overridden for each individual request to {@link jQuery#ajax} later on.
46 mw.Api = function ( options ) {
48 if ( options === undefined ) {
52 // Force toString if we got a mw.Uri object
53 if ( options.ajax && options.ajax.url !== undefined ) {
54 options.ajax.url = String( options.ajax.url );
57 options.parameters = $.extend( {}, defaultOptions.parameters, options.parameters );
58 options.ajax = $.extend( {}, defaultOptions.ajax, options.ajax );
60 this.defaults = options;
66 * Normalize the ajax options for compatibility and/or convenience methods.
68 * @param {Object} [arg] An object contaning one or more of options.ajax.
69 * @return {Object} Normalized ajax options.
71 normalizeAjaxOptions: function ( arg ) {
72 // Arg argument is usually empty
73 // (before MW 1.20 it was used to pass ok callbacks)
75 // Options can also be a success callback handler
76 if ( typeof arg === 'function' ) {
83 * Perform API get request
85 * @param {Object} parameters
86 * @param {Object|Function} [ajaxOptions]
87 * @return {jQuery.Promise}
89 get: function ( parameters, ajaxOptions ) {
90 ajaxOptions = this.normalizeAjaxOptions( ajaxOptions );
91 ajaxOptions.type = 'GET';
92 return this.ajax( parameters, ajaxOptions );
96 * Perform API post request
98 * TODO: Post actions for non-local hostnames will need proxy.
100 * @param {Object} parameters
101 * @param {Object|Function} [ajaxOptions]
102 * @return {jQuery.Promise}
104 post: function ( parameters, ajaxOptions ) {
105 ajaxOptions = this.normalizeAjaxOptions( ajaxOptions );
106 ajaxOptions.type = 'POST';
107 return this.ajax( parameters, ajaxOptions );
111 * Perform the API call.
113 * @param {Object} parameters
114 * @param {Object} [ajaxOptions]
115 * @return {jQuery.Promise} Done: API response data. Fail: Error code
117 ajax: function ( parameters, ajaxOptions ) {
119 apiDeferred = $.Deferred(),
122 parameters = $.extend( {}, this.defaults.parameters, parameters );
123 ajaxOptions = $.extend( {}, this.defaults.ajax, ajaxOptions );
125 // Ensure that token parameter is last (per [[mw:API:Edit#Token]]).
126 if ( parameters.token ) {
127 token = parameters.token;
128 delete parameters.token;
130 // Some deployed MediaWiki >= 1.17 forbid periods in URLs, due to an IE XSS bug
131 // So let's escape them here. See bug #28235
132 // This works because jQuery accepts data as a query string or as an Object
133 ajaxOptions.data = $.param( parameters ).replace( /\./g, '%2E' );
135 // If we extracted a token parameter, add it back in.
137 ajaxOptions.data += '&token=' + encodeURIComponent( token );
140 // Backwards compatibility: Before MediaWiki 1.20,
141 // callbacks were done with the 'ok' and 'err' property in ajaxOptions.
142 if ( ajaxOptions.ok ) {
143 apiDeferred.done( ajaxOptions.ok );
144 delete ajaxOptions.ok;
146 if ( ajaxOptions.err ) {
147 apiDeferred.fail( ajaxOptions.err );
148 delete ajaxOptions.err;
151 // Make the AJAX request
152 xhr = $.ajax( ajaxOptions )
153 // If AJAX fails, reject API call with error code 'http'
154 // and details in second argument.
155 .fail( function ( xhr, textStatus, exception ) {
156 apiDeferred.reject( 'http', {
158 textStatus: textStatus,
162 // AJAX success just means "200 OK" response, also check API error codes
163 .done( function ( result ) {
164 if ( result === undefined || result === null || result === '' ) {
165 apiDeferred.reject( 'ok-but-empty',
166 'OK response but empty result (check HTTP headers?)'
168 } else if ( result.error ) {
169 var code = result.error.code === undefined ? 'unknown' : result.error.code;
170 apiDeferred.reject( code, result );
172 apiDeferred.resolve( result );
176 // Return the Promise
177 return apiDeferred.promise( { abort: xhr.abort } ).fail( function ( code, details ) {
178 mw.log( 'mw.Api error: ', code, details );
183 * Post to API with specified type of token. If we have no token, get one and try to post.
184 * If we have a cached token try using that, and if it fails, blank out the
185 * cached token and start over. For example to change an user option you could do:
187 * new mw.Api().postWithToken( 'options', {
189 * optionname: 'gender',
190 * optionvalue: 'female'
193 * @param {string} tokenType The name of the token, like options or edit.
194 * @param {Object} params API parameters
195 * @return {jQuery.Promise} See #post
197 postWithToken: function ( tokenType, params ) {
198 var api = this, hasOwn = tokenCache.hasOwnProperty;
199 if ( hasOwn.call( tokenCache, tokenType ) && tokenCache[tokenType] !== undefined ) {
200 params.token = tokenCache[tokenType];
201 return api.post( params ).then(
204 if ( code === 'badtoken' ) {
205 // force a new token, clear any old one
206 tokenCache[tokenType] = params.token = undefined;
207 return api.post( params );
209 // Pass the promise forward, so the caller gets error codes
214 return api.getToken( tokenType ).then( function ( token ) {
215 tokenCache[tokenType] = params.token = token;
216 return api.post( params );
222 * Api helper to grab any token.
224 * @param {string} type Token type.
225 * @return {jQuery.Promise}
226 * @return {Function} return.done
227 * @return {string} return.done.token Received token.
229 getToken: function ( type ) {
233 apiPromise = this.get( {
237 // Due to the API assuming we're logged out if we pass the callback-parameter,
238 // we have to disable jQuery's callback system, and instead parse JSON string,
239 // by setting 'jsonp' to false.
240 // TODO: This concern seems genuine but no other module has it. Is it still
241 // needed and/or should we pass this by default?
243 .done( function ( data ) {
244 // If token type is not available for this user,
245 // key '...token' is missing or can contain Boolean false
246 if ( data.tokens && data.tokens[type + 'token'] ) {
247 d.resolve( data.tokens[type + 'token'] );
249 d.reject( 'token-missing', data );
254 return d.promise( { abort: apiPromise.abort } );
261 * List of errors we might receive from the API.
262 * For now, this just documents our expectation that there should be similar messages
266 // occurs when POST aborted
267 // jQuery 1.4 can't distinguish abort or lost connection from 200 OK + empty result
273 // really a warning, but we treat it like an error
277 // upload succeeded, but no image info.
278 // this is probably impossible, but might as well check for it
280 // remote errors, defined in API
289 'copyuploaddisabled',
295 'filetype-banned-type',
298 'verification-error',
305 'fileexists-shared-forbidden',
313 * List of warnings we might receive from the API.
314 * For now, this just documents our expectation that there should be similar messages
322 }( mediaWiki, jQuery ) );