Abort all unfinished requests issued by this Api object.

Perform the API call.

A promise that settles when the API response is processed.Has an 'abort' method which can be used to abort the request.Seemw.Api~AbortablePromise for an example.

• On success, resolves to( result, jqXHR ) whereresult is the parsed API response.
• On an API error, rejects with( code, result, result, jqXHR ) wherecode is theAPI error code, andresultis as above. When there are multiple errors, the code from the first one will be used.If there is no error code, "unknown" is used.
• On other types of errors, rejects with( 'http', details ) wheredetails is an objectwith three fields:xhr (the jqXHR object),textStatus, andexception.The meaning of the last two fields is as follows:
  • When the request is aborted (the abort method of the promise is called), textStatusand exception are both set to "abort".
  • On a network timeout, textStatus and exception are both set to "timeout".
  • On a network error, textStatus is "error" and exception is the empty string.
  • When the HTTP response code is anything other than 2xx or 304 (the API does notuse such response codes but some intermediate layer might), textStatus is "error"and exception is the HTTP status text (the text following the status code in thefirst line of the server response). For HTTP/2,exception is always an empty string.
  • When the response is not valid JSON but the previous error conditions aren't met,textStatus is "parsererror" and exception is the exception object thrown byJSON.parse.

Extend an API parameter object with an assertion that the user won't change.

This is useful for API calls which create new revisions or log entries. When the currentpage was loaded when the user was logged in, but at the time of the API call the useris not logged in anymore (e.g. due to session expiry), their IP is recorded in the pagehistory or log, which can cause serious privacy issues. Extending the API parameters viathis method ensures that that won't happen, by checking the user's identity that wasembedded into the page when it was rendered against the active session on the server.

When the assertion fails, the API request will fail, with one of the following error codes:

• apierror-assertanonfailed: when the client-side logic thinks the user is anonymousbut the server thinks it is logged in;
• apierror-assertuserfailed: when the client-side logic thinks the user is logged in but theserver thinks it is anonymous;
• apierror-assertnameduserfailed: when both the client-side logic and the server thinks theuser is logged in but they see it logged in under a different username.

Indicate that the cached token for a certain action of the API is bad.

Call this if you get a 'badtoken' error when using the token returned bygetToken().You may also want to usepostWithToken() instead, which invalidates bad cached tokensautomatically.

Upload a file in several chunks.

Upload a file to the stash, in chunks.

This function will return a promise, which when resolved, will pass back a functionto finish the stash upload.

Promise that resolves with afunction that should be called to finish the upload.

Create a new page.

API response

Edit an existing page.

To create a new page, use #create() instead.

Simple transformation:

new mw.Api()    .edit( 'Sandbox', function ( revision ) {        return revision.content.replace( 'foo', 'bar' );    } )    .then( function () {        console.log( 'Saved!' );    } );

Set save parameters by returning an object instead of a string:

new mw.Api().edit(    'Sandbox',    function ( revision ) {        return {            text: revision.content.replace( 'foo', 'bar' ),            summary: 'Replace "foo" with "bar".',            assert: 'bot',            minor: true        };    }).then( function () {    console.log( 'Saved!' );} );

Transform asynchronously by returning a promise.

new mw.Api()    .edit( 'Sandbox', function ( revision ) {        return Spelling            .corrections( revision.content )            .then( function ( report ) {                return {                    text: report.output,                    summary: report.changelog                };            } );    } )    .then( function () {        console.log( 'Saved!' );    } );

Edit API response

Perform API get request. Seeajax() for details.

Get the categories that a particular page on the wiki belongs to.

Promise that resolves with an array ofcategory titles, or with false if the title was not found.

Get a list of categories that match a certain prefix.

E.g. given "Foo", return "Food", "Foolish people", "Foosball tables"...

Promise that resolves with an array of matched categories

API helper to grab a csrf token.

Received token.

Given an API response indicating an error, get a jQuery object containing a human-readableerror message that you can display somewhere on the page.

For better quality of error messages, it's recommended to use the following options in yourAPI queries:

errorformat: 'html',errorlang: mw.config.get( 'wgUserLanguage' ),errorsuselocal: true,

Error messages, particularly for editing pages, may consist of multiple paragraphs of text.Your user interface should have enough space for that.

Error messages, each wrapped in a<div>

Get a set of messages.

Get a token for a certain action from the API.

Received token.

Get the current user's groups and rights.

Determine if a category exists.

Promise that resolves with a boolean indicatingwhether the category exists.

Loads a set of messages and add them tomw.messages.

Loads a set of messages and add them tomw.messages. Only messages that are not already knownare loaded. If all messages are known, the returned promise is resolved immediately.

Seepost()

Helper for adding support for abortable promises in mw.Api methods.

This methods does three things:

• Returns an object with anabort method that can be used as a base foranmw.Api~AbortablePromise.
• Updates the providedajaxOptions with asignal that will be triggered by said method.
• If theajaxOptions already had asignal, forwards evens from it to the new one.

This ensures that both the signal provided inajaxOptions (if any) and theabort method on the returned object can cancel the HTTP requests.It's only needed when supporting the old-stylepromise.abort() method.

Base object formw.Api~AbortablePromise

Post a new section to the page.

Convenience method for 'action=parse'.

Promise that resolves with the parsed HTML ofwikitext

Perform API post request. Seeajax() for details.

Post to API withcsrf token. See#postWithToken

See#post

Post to API with the specified type of token. If we have no token, get one and try to post.If we already have a cached token, try using that, and if the request fails using the cached token,blank it out and start over.

Seepost()

Prepare an extensible API request.

This is a utility method to allow mw.hook implementations to add data to params sentwith an API request.

For example usage, see mediawiki.ready/index.js#logoutViaPost:api.prepareExtensibleApiRequest( 'extendLogout' ).then( ( params ) => { ... } )

Implementations ofhookName should do something like the following, wherehookNameisextendLogout in this example:

mw.hook( 'extendLogout' ).add( ( data ) => {data.promise = data.promise.then( () => {// Return a promisereturn collectClientHintsData().then( ( userAgentHighEntropyValues ) => {// Set the data.params.{yourUniqueKey} that will be included in the API// requestdata.params.customData = { clientHints: userAgentHighEntropyValues };} );} );} );

Updated parameter data from implementationsofhookName to include with the API request.

Convenience method foraction=rollback.

Asynchronously save the value of a single user option using the API.SeesaveOptions().

Asynchronously save the values of user options using theOptions API.

If a value ofnull is provided, the given option will be reset to the default value.

Any warnings returned by the API, including warnings about invalid option names or values,are ignored. However, do not rely on this behavior.

If necessary, the options will be saved using several sequential API requests. Only one promiseis always returned that will be resolved when all requests complete.

If a request from a previoussaveOptions() call is still pending, this will wait for it to becompleted, otherwise MediaWiki gets sad. No requests are sent for anonymous users, as theywould fail anyway. SeeT214963.

Convenience method foraction=watch&unwatch=1.

A promise that resolveswith an object (or array of objects) describing each page that was passed in and itscurrent watched/unwatched status.

Upload a file to MediaWiki.

The file will be uploaded using AJAX and FormData.

Finish an upload in the stash.

Upload a file to the stash.

This function will return a promise, which when resolved, will pass back a functionto finish the stash upload. You can call that function with an argument containingmore, or conflicting, data to pass to the server.

Promise that resolves with afunction that should be called to finish the upload.

Convenience method foraction=watch.

A promise that resolveswith an object (or array of objects) describing each page that was passed in and itscurrent watched/unwatched status.

New content, object with editAPI parameters, or promise providing one of those.