Class: MatrixHttpApi

http-api.MatrixHttpApi

new MatrixHttpApi(event_emitter, opts)

Construct a MatrixHttpApi.
Parameters:
Name Type Description
event_emitter EventEmitter The event emitter to use for emitting events
opts Object The options to use for this HTTP API.
Properties
Name Type Attributes Description
baseUrl string Required. The base client-server URL e.g. 'http://localhost:8008'.
request function Required. The function to call for HTTP requests. This function must look like function(opts, callback){ ... }.
prefix string Required. The matrix client prefix to use, e.g. '/_matrix/client/r0'. See PREFIX_R0 and PREFIX_UNSTABLE for constants.
onlyData bool <optional>
True to return only the 'data' component of the response (e.g. the parsed HTTP body). If false, requests will return an object with the properties code, headers and data.
accessToken string The access_token to send with requests. Can be null to not send an access token.
extraParams Object Optional. Extra query parameters to send on requests.
Source:

Methods

authedRequest(callback, method, path, queryParamsopt, data, optsopt) → {module:client.Promise|module:http-api.MatrixError}

Perform an authorised request to the homeserver.
Parameters:
Name Type Attributes Description
callback function Optional. The callback to invoke on success/failure. See the promise return values for more information.
method string The HTTP method e.g. "GET".
path string The HTTP path after the supplied prefix e.g. "/createRoom".
queryParams Object <optional>
A dict of query params (these will NOT be urlencoded). If unspecified, there will be no query params.
data Object The HTTP JSON body.
opts Object <optional>
additional options
Properties
Name Type Attributes Description
localTimeoutMs Number <optional>
The maximum amount of time to wait before timing out the request. If not specified, there is no timeout.
prefix sting <optional>
The full prefix to use e.g. "/_matrix/client/v2_alpha". If not specified, uses this.opts.prefix.
headers Object <optional>
map of additional request headers
Source:
Returns:
  • Resolves to {data: {Object}, headers: {Object}, code: {Number}}. If onlyData is set, this will resolve to the data object only.
    Type
    module:client.Promise
  • Rejects with an error if a problem occurred. This includes network problems and Matrix-specific error JSON.
    Type
    module:http-api.MatrixError

authedRequestWithPrefix(callback, method, path, queryParams, data, prefix, localTimeoutMsopt) → {module:client.Promise|module:http-api.MatrixError}

Perform an authorised request to the homeserver with a specific path prefix which overrides the default for this call only. Useful for hitting different Matrix Client-Server versions.
Parameters:
Name Type Attributes Description
callback function Optional. The callback to invoke on success/failure. See the promise return values for more information.
method string The HTTP method e.g. "GET".
path string The HTTP path after the supplied prefix e.g. "/createRoom".
queryParams Object A dict of query params (these will NOT be urlencoded).
data Object The HTTP JSON body.
prefix string The full prefix to use e.g. "/_matrix/client/v2_alpha".
localTimeoutMs Number <optional>
The maximum amount of time to wait before timing out the request. If not specified, there is no timeout.
Deprecated:
  • prefer authedRequest with opts.prefix
Source:
Returns:
  • Resolves to {data: {Object}, headers: {Object}, code: {Number}}. If onlyData is set, this will resolve to the data object only.
    Type
    module:client.Promise
  • Rejects with an error if a problem occurred. This includes network problems and Matrix-specific error JSON.
    Type
    module:http-api.MatrixError

getContentUri() → {Object}

Get the content repository url with query parameters.
Source:
Returns:
An object with a 'base', 'path' and 'params' for base URL, path and query parameters respectively.
Type
Object

getUrl(path, queryParams, prefix) → {string}

Form and return a homeserver request URL based on the given path params and prefix.
Parameters:
Name Type Description
path string The HTTP path after the supplied prefix e.g. "/createRoom".
queryParams Object A dict of query params (these will NOT be urlencoded).
prefix string The full prefix to use e.g. "/_matrix/client/v2_alpha".
Source:
Returns:
URL
Type
string

request(callback, method, path, queryParamsopt, data, optsopt) → {module:client.Promise|module:http-api.MatrixError}

Perform a request to the homeserver without any credentials.
Parameters:
Name Type Attributes Description
callback function Optional. The callback to invoke on success/failure. See the promise return values for more information.
method string The HTTP method e.g. "GET".
path string The HTTP path after the supplied prefix e.g. "/createRoom".
queryParams Object <optional>
A dict of query params (these will NOT be urlencoded). If unspecified, there will be no query params.
data Object The HTTP JSON body.
opts Object <optional>
additional options
Properties
Name Type Attributes Description
localTimeoutMs Number <optional>
The maximum amount of time to wait before timing out the request. If not specified, there is no timeout.
prefix sting <optional>
The full prefix to use e.g. "/_matrix/client/v2_alpha". If not specified, uses this.opts.prefix.
headers Object <optional>
map of additional request headers
Source:
Returns:
  • Resolves to {data: {Object}, headers: {Object}, code: {Number}}. If onlyData is set, this will resolve to the data object only.
    Type
    module:client.Promise
  • Rejects with an error if a problem occurred. This includes network problems and Matrix-specific error JSON.
    Type
    module:http-api.MatrixError

requestOtherUrl(callback, method, uri, queryParamsopt, data, optsopt) → {module:client.Promise|module:http-api.MatrixError}

Perform a request to an arbitrary URL.
Parameters:
Name Type Attributes Description
callback function Optional. The callback to invoke on success/failure. See the promise return values for more information.
method string The HTTP method e.g. "GET".
uri string The HTTP URI
queryParams Object <optional>
A dict of query params (these will NOT be urlencoded). If unspecified, there will be no query params.
data Object The HTTP JSON body.
opts Object <optional>
additional options
Properties
Name Type Attributes Description
localTimeoutMs Number <optional>
The maximum amount of time to wait before timing out the request. If not specified, there is no timeout.
prefix sting <optional>
The full prefix to use e.g. "/_matrix/client/v2_alpha". If not specified, uses this.opts.prefix.
headers Object <optional>
map of additional request headers
Source:
Returns:
  • Resolves to {data: {Object}, headers: {Object}, code: {Number}}. If onlyData is set, this will resolve to the data object only.
    Type
    module:client.Promise
  • Rejects with an error if a problem occurred. This includes network problems and Matrix-specific error JSON.
    Type
    module:http-api.MatrixError

requestWithPrefix(callback, method, path, queryParams, data, prefix, localTimeoutMsopt) → {module:client.Promise|module:http-api.MatrixError}

Perform a request to the homeserver without any credentials but with a specific path prefix which overrides the default for this call only. Useful for hitting different Matrix Client-Server versions.
Parameters:
Name Type Attributes Description
callback function Optional. The callback to invoke on success/failure. See the promise return values for more information.
method string The HTTP method e.g. "GET".
path string The HTTP path after the supplied prefix e.g. "/createRoom".
queryParams Object A dict of query params (these will NOT be urlencoded).
data Object The HTTP JSON body.
prefix string The full prefix to use e.g. "/_matrix/client/v2_alpha".
localTimeoutMs Number <optional>
The maximum amount of time to wait before timing out the request. If not specified, there is no timeout.
Deprecated:
  • prefer request with opts.prefix
Source:
Returns:
  • Resolves to {data: {Object}, headers: {Object}, code: {Number}}. If onlyData is set, this will resolve to the data object only.
    Type
    module:client.Promise
  • Rejects with an error if a problem occurred. This includes network problems and Matrix-specific error JSON.
    Type
    module:http-api.MatrixError

uploadContent(file, opts) → {module:client.Promise}

Upload content to the Home Server
Parameters:
Name Type Description
file object The object to upload. On a browser, something that can be sent to XMLHttpRequest.send (typically a File). Under node.js, a a Buffer, String or ReadStream.
opts object options object
Properties
Name Type Attributes Description
name string <optional>
Name to give the file on the server. Defaults to file.name.
type string <optional>
Content-type for the upload. Defaults to file.type, or applicaton/octet-stream.
rawResponse boolean <optional>
Return the raw body, rather than parsing the JSON. Defaults to false (except on node.js, where it defaults to true for backwards compatibility).
onlyContentUri boolean <optional>
Just return the content URI, rather than the whole body. Defaults to false (except on browsers, where it defaults to true for backwards compatibility). Ignored if opts.rawResponse is true.
callback function <optional>
Deprecated. Optional. The callback to invoke on success/failure. See the promise return values for more information.
Source:
Returns:
Resolves to response object, as determined by this.opts.onlyData, opts.rawResponse, and opts.onlyContentUri. Rejects with an error (usually a MatrixError).
Type
module:client.Promise