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
26 * Constructor to create an object to interact with the API of a particular MediaWiki server.
27 * mw.Api objects represent the API of a particular MediaWiki server.
29 * TODO: Share API objects with exact same config.
31 * var api = new mw.Api();
35 * } ).done ( function ( data ) {
36 * console.log( data );
42 * @param {Object} options See defaultOptions documentation above. Ajax options can also be
43 * overridden for each individual request to {@link jQuery#ajax} later on.
45 mw
.Api = function ( options
) {
47 if ( options
=== undefined ) {
51 // Force toString if we got a mw.Uri object
52 if ( options
.ajax
&& options
.ajax
.url
!== undefined ) {
53 options
.ajax
.url
= String( options
.ajax
.url
);
56 options
.parameters
= $.extend( {}, defaultOptions
.parameters
, options
.parameters
);
57 options
.ajax
= $.extend( {}, defaultOptions
.ajax
, options
.ajax
);
59 this.defaults
= options
;
65 * Normalize the ajax options for compatibility and/or convenience methods.
67 * @param {Object} [arg] An object contaning one or more of options.ajax.
68 * @return {Object} Normalized ajax options.
70 normalizeAjaxOptions: function ( arg
) {
71 // Arg argument is usually empty
72 // (before MW 1.20 it was used to pass ok callbacks)
74 // Options can also be a success callback handler
75 if ( typeof arg
=== 'function' ) {
82 * Perform API get request
84 * @param {Object} parameters
85 * @param {Object|Function} [ajaxOptions]
86 * @return {jQuery.Promise}
88 get: function ( parameters
, ajaxOptions
) {
89 ajaxOptions
= this.normalizeAjaxOptions( ajaxOptions
);
90 ajaxOptions
.type
= 'GET';
91 return this.ajax( parameters
, ajaxOptions
);
95 * Perform API post request
97 * TODO: Post actions for non-local hostnames will need proxy.
99 * @param {Object} parameters
100 * @param {Object|Function} [ajaxOptions]
101 * @return {jQuery.Promise}
103 post: function ( parameters
, ajaxOptions
) {
104 ajaxOptions
= this.normalizeAjaxOptions( ajaxOptions
);
105 ajaxOptions
.type
= 'POST';
106 return this.ajax( parameters
, ajaxOptions
);
110 * Perform the API call.
112 * @param {Object} parameters
113 * @param {Object} [ajaxOptions]
114 * @return {jQuery.Promise} Done: API response data. Fail: Error code
116 ajax: function ( parameters
, ajaxOptions
) {
118 apiDeferred
= $.Deferred();
120 parameters
= $.extend( {}, this.defaults
.parameters
, parameters
);
121 ajaxOptions
= $.extend( {}, this.defaults
.ajax
, ajaxOptions
);
123 // Ensure that token parameter is last (per [[mw:API:Edit#Token]]).
124 if ( parameters
.token
) {
125 token
= parameters
.token
;
126 delete parameters
.token
;
128 // Some deployed MediaWiki >= 1.17 forbid periods in URLs, due to an IE XSS bug
129 // So let's escape them here. See bug #28235
130 // This works because jQuery accepts data as a query string or as an Object
131 ajaxOptions
.data
= $.param( parameters
).replace( /\./g, '%2E' );
133 // If we extracted a token parameter, add it back in.
135 ajaxOptions
.data
+= '&token=' + encodeURIComponent( token
);
138 // Backwards compatibility: Before MediaWiki 1.20,
139 // callbacks were done with the 'ok' and 'err' property in ajaxOptions.
140 if ( ajaxOptions
.ok
) {
141 apiDeferred
.done( ajaxOptions
.ok
);
142 delete ajaxOptions
.ok
;
144 if ( ajaxOptions
.err
) {
145 apiDeferred
.fail( ajaxOptions
.err
);
146 delete ajaxOptions
.err
;
149 // Make the AJAX request
150 $.ajax( ajaxOptions
)
151 // If AJAX fails, reject API call with error code 'http'
152 // and details in second argument.
153 .fail( function ( xhr
, textStatus
, exception
) {
154 apiDeferred
.reject( 'http', {
156 textStatus
: textStatus
,
160 // AJAX success just means "200 OK" response, also check API error codes
161 .done( function ( result
) {
162 if ( result
=== undefined || result
=== null || result
=== '' ) {
163 apiDeferred
.reject( 'ok-but-empty',
164 'OK response but empty result (check HTTP headers?)'
166 } else if ( result
.error
) {
167 var code
= result
.error
.code
=== undefined ? 'unknown' : result
.error
.code
;
168 apiDeferred
.reject( code
, result
);
170 apiDeferred
.resolve( result
);
174 // Return the Promise
175 return apiDeferred
.promise().fail( function ( code
, details
) {
176 mw
.log( 'mw.Api error: ', code
, details
);
185 * List of errors we might receive from the API.
186 * For now, this just documents our expectation that there should be similar messages
190 // occurs when POST aborted
191 // jQuery 1.4 can't distinguish abort or lost connection from 200 OK + empty result
197 // really a warning, but we treat it like an error
201 // upload succeeded, but no image info.
202 // this is probably impossible, but might as well check for it
204 // remote errors, defined in API
213 'copyuploaddisabled',
219 'filetype-banned-type',
222 'verification-error',
229 'fileexists-shared-forbidden',
237 * List of warnings we might receive from the API.
238 * For now, this just documents our expectation that there should be similar messages
246 }( mediaWiki
, jQuery
) );