m3api: Class: Session

Constructor

new Session(apiUrl, defaultParamsopt, defaultOptionsopt)

Parameters:

Name	Type	Attributes	Description
`apiUrl`	string		The URL to the api.php endpoint, such as https://en.wikipedia.org/w/api.php. Can also be just the domain, such as en.wikipedia.org.
`defaultParams`	Params	<optional>	Parameters to include in every API request. You are strongly encouraged to specify formatversion: 2 here; other useful global parameters include uselang, errorformat, maxlag.
`defaultOptions`	Options	<optional>	Options to set for each request. You are strongly encouraged to specify a userAgent according to the User-Agent policy.

Source:

core.js, line 448

Members

apiUrl :string

The URL to the api.php endpoint. Must not be reassigned.

Type:

string

Source:

core.js, line 472

defaultOptions :Options

Options to set for each request. Can be modified after construction.

Type:

Options

Source:

core.js, line 489

defaultParams :Object

Parameters to include in every API request. Can be modified after construction, e.g. to add assert=user after logging in.

Type:

Object

Source:

core.js, line 481

tokens :Map

Saved/cached tokens. Can be modified after construction, particularly to call clear() after logging in or out; apart from that, however, using the tokenType/tokenName options or Session#getToken is generally more convenient.

Type:

Source:

core.js, line 501

Methods

(protected) getRequestHeaders(options) → {Object}

Get the effective request headers for these options.

Parameters:

Name	Type	Description
`options`	Options

Source:

core.js, line 720

Returns:

Type: Object

(async) getToken(type, options) → {string}

Get a token of the specified type.

Though this method is public, it should generally not be used directly: call Session#request with the tokenType/tokenName options instead.

Parameters:

Name	Type	Description
`type`	string
`options`	Options	Options for the request to get the token.

Source:

core.js, line 685

Returns:

Type: string

(protected) getUserAgent(options) → {string}

Get the effective user agent string for these options.

Parameters:

Name	Type	Description
`options`	Options

Source:

core.js, line 742

Returns:

Type: string

(abstract, protected) internalGet(apiUrl, params, headers) → {Promise.<InternalResponse>}

Actually make a GET request.

Parameters:

Name	Type	Description
`apiUrl`	string
`params`	Object
`headers`	Object	Header names must be all-lowercase.

Source:

core.js, line 838

Returns:

Type: Promise.<InternalResponse>

(abstract, protected) internalPost(apiUrl, urlParams, bodyParams, headers) → {Promise.<InternalResponse>}

Actually make a POST request.

Parameters:

Name	Type	Description
`apiUrl`	string
`urlParams`	Object
`bodyParams`	Object
`headers`	Object	Header names must be all-lowercase.

Source:

core.js, line 853

Returns:

Type: Promise.<InternalResponse>

(async) request(params, optionsopt) → {Object}

Make an API request.

Parameters:

Name	Type	Attributes	Description
`params`	Params		The parameters. Default parameters from the constructor are added to these, with per-request parameters overriding default parameters in case of collision.
`options`	Options	<optional>	Other options for the request. The per-request options extend and override the options passed into the constructor, which in turn extend and override the builtin DEFAULT_OPTIONS.

Source:

core.js, line 516

Throws:

ApiErrors

Returns:

Type: Object

(async, generator) requestAndContinue(params, optionsopt) → {Object}

Make a series of API requests, following API continuation.

Parameters:

Name	Type	Attributes	Description
`params`	Params		Same as for Session#request. Continuation parameters will be added automatically.
`options`	Options	<optional>	Same as for Session#request.

Source:

core.js, line 614

Throws:

ApiErrors

Yields:

Type: Object

(async, generator) requestAndContinueReducingBatch(params, options, reducer, initialopt) → {*}

Make a series of API requests, following API continuation, accumulating responses and yielding one result per batch.

This works conceptually similar to Array.reduce(), but repeatedly, with each batch of responses corresponding to one array. At the beginning of each batch, an initial value is generated, and then for each response in the batch, a reducer is called with the current value and that response. (The current value starts out as the initial value; afterwards, it’s the reducer’s return value for the previous response.) At the end of each batch, the current value is yielded, and the process starts over with a new initial value.

The reducer will typically extract some kind of pages or other entries from the response, add them to the current value, possibly merging them with existing entries there, and then return the updated value. The initial callback defaults to producing empty objects, but other values are also possible: sets or maps may be useful.

Parameters:

Name	Type	Attributes	Description
`params`	Params		Same as for Session#request.
`options`	Options		Same as for Session#request. (But not optional here!) The dropTruncatedResultWarning option defaults to true here, since continuation will produce the rest of the truncated result automatically.
`reducer`	function		A callback like for Array.reduce(). Called with two arguments, the current value and the current response.
`initial`	function	<optional>	A callback producing initial values. Called with no arguments. Defaults to producing empty objects.

Source:

core.js, line 658

Yields:

The last reducer return value for each batch. Typically, the initial and reducer callbacks will have the same return type, which will then also be the return type of this function, such as Object, Map, or Set.

Type: *