Class: Session

Session(apiUrl, defaultParamsopt, defaultOptionsopt)

A session to make API requests.

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:

Members

apiUrl :string

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

Type:
  • string
Source:

defaultOptions :Options

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

Type:
Source:

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:

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:
  • Map
Source:

Methods

(abstract, protected) fetch(resource, fetchOptions) → {Promise.<Response>}

Internal function to actually make a network request. (You almost certainly want to use Session#request instead.)

This represents a subset of the standard fetch() API, with the following differences:

  1. The resource must be a URL, not a string.
  2. The fetchOptions object is required.
  3. Only the following options are supported:
    • method (must be set)
    • headers (must be set and contain a User-Agent header)
    • body (only string, FormData and URLSearchParams values are supported)

Implementations may support additional fetch() features as long as they are part of the standard, but they must not support nonstandard features; they must ignore any unknown features. Callers may pass in additional options, as long as they are part of the standard, but only if they are not required for the request to succeed; they must not pass in nonstandard options.

Parameters:
Name Type Description
resource URL
fetchOptions RequestInit

(In the standard fetch() API, this is just called “options”, but Options are something else in m3api.)
Source:
Returns:
Type
Promise.<Response>

(protected) getAuthorizationHeader(options) → {string|null}

Get the Authorization: header for these options.

Parameters:
Name Type Description
options Options
Source:
Returns:
Type
string | null

(protected) getRequestHeaders(options) → {Object}

Get the effective request headers for these options.

Parameters:
Name Type Description
options Options
Source:
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:
Returns:
Type
string

(protected) getUserAgent(options) → {string}

Get the effective user agent string for these options.

Parameters:
Name Type Description
options Options
Source:
Returns:
Type
string

(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:
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:
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:
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
*