Skip to content

Sending Requests

Jump to bottom
Dickson Law edited this page Apr 9, 2023 · 2 revisions

Sending Requests

  • xhr_request(verb, url, body, options): Send off a HTTP request, then return the asynchronous request ID.

Shortcut Functions

These functions are shorthands for sending requests with specific verbs.

Verbs Without Body

  • xhr_get(url, options)
  • xhr_head(url, options)
  • xhr_options(url, options)
  • xhr_trace(url, options)

Verbs With Body

The body may be specified as an untyped struct or one of the request body class types.

  • xhr_delete(url, body, options)
  • xhr_patch(url, body, options)
  • xhr_post(url, body, options)
  • xhr_put(url, body, options)

The options Parameter

The options parameter is an untyped struct specifying additional properties for the request and what to do while handling the response. Available keys are:

  • decoder: Specify a method that accepts the response as a string and returns a decoded result. If specified as undefined, the response will be returned as-is. Leave unspecified to use the default set by REQM_DEFAULT_DECODER
  • done: Specify a callback method that accepts a XhrResponse struct and performs actions on it when successful.
  • encoder: Specify a function that accepts a struct and returns a typed struct containing setHeader(map), addKey(k, v), getBody() and cleanBody(body) methods. Only applicable when a plain struct is passed as the body.
  • fail: Specify a callback method that accepts a XhrResponse struct and performs actions on it when the request is unsuccessful and/or the decoder throws an exception.
  • headers: Specify a map ID or array with pairwise header-value entries, and add those to the request's headers. For example, specifying [["Accept", "application/json"], ["Accept-Charset", "utf-8"]] here will ask the server to respond in UTF-8 JSON if able.
  • params: If specified as an untyped struct, it will be URL-encoded and appended to the URL. For example, specifying {q: "Hello World"} here will append ?q=Hello%20World to the URL.
  • progress: Specify a callback method that accepts the current download progress and the total size of the download, and performs actions on it when the request is in progress.
  • subject: Specify an instance ID to bind callback methods to. The daemon will also monitor its existence, and self-destruct if it no longer exists. If specified as noone, the daemon will not monitor anything else. Leave unspecified to use the default set by REQM_DEFALT_SUBJECT.

Classes

XhrResponse

The done and fail options take XhrResponse structs, which describe the outcome of the request.

Fields

  • data: The decoded result of the response. If decode was unsuccessful, this will contain undefined.
  • decodeOk: Whether the decode was successful.
  • decodeException: (if decode failed) The exception thrown by the decoder.
  • handle: The asynchronous request ID.
  • headers: A map containing the headers of the response.
  • httpStatus: The HTTP status code of the response (e.g. 200).
  • url: The URL being requested.

Methods

  • isSuccessful(): Return whether the request is considered successful (decode is OK, HTTP status is 2xx)

Clone this wiki locally