mediawiki.api does not use consistent reject parameters
Open, Needs TriagePublic

Description

When you have a mediawiki.api promise and it was rejected, the list of arguments could take five (!!) different forms depending on what code rejected it:

// Form 1: (error code, object with XHR)
apiDeferred.reject( 'http', {
	xhr: xhr,
	textStatus: textStatus,
	exception: exception
} );

// Form 2: (error code, object without XHR)
abortedPromise = $.Deferred().reject( 'http',
	{ textStatus: 'abort', exception: 'abort' } ).promise(),

// Form 3: (error code, message, result object, XHR)
apiDeferred.reject( 'ok-but-empty',
	'OK response but empty result (check HTTP headers?)',
	result,
	jqXHR
);

// Form 4: (error code, result object, result object, XHR)
apiDeferred.reject( code, result, result, jqXHR );

// Form 5: (error code, result object)
return $.Deferred().reject( 'token-missing', res );

(Form 2 is specific to postWithToken, and form 5 is specific to getToken/postWithToken)

This makes it impossible to use the information passed in these parameters in a reasonable way. The only thing that is consistently present is the error code. The XHR object is not always present (forms 2 and 5 vs the others) and when it is, it's not always in the same place (inside an object vs as the fourth parameter). The second parameter is sometimes an object with information about the error, sometimes a string with information about the error, and sometimes the object returned by the API. The third and fourth parameters aren't always present (which is fine), and are consistent when they are present.

mediawiki.api also doesn't document what the rejection parameters look like at all. If and when these inconsistencies are fixed, the reject parms should be clearly documented to make it less likely that things will get this crazy again.

Catrope created this task.Sep 26 2017, 5:11 AM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptSep 26 2017, 5:11 AM
TheDJ added a subscriber: TheDJ.Sep 26 2017, 8:26 AM

How did 'Form 4' come to pass?

Given that users may expecting any of these forms, how can we change the API in a way that doesn't cause regressions?