Skip to main content

HTTP

All HTTP functions automatically retry failed requests based on the rules described here.

The maximum request body size is 50 MB; larger requests are aborted and reported as an error.

The response body is returned as a string, including for 4xx and 5xx status codes. Connection errors throw after all retries are exhausted.

http_get​

Performs an HTTP GET request on the URL path appended to the account URL.

Returns the response body as a string.

Package account is used if not defined as second parameter.

http_get(url, [account]);

Example:

let url = "/data";
let result = http_get(url, "tw");
log("response:", result);

http_query​

Performs an HTTP QUERY request with data on the URL path appended to the account URL.

QUERY (RFC 10008) retrieves data like GET does, but sends the parameters in the request body instead of the URL. Use it when the parameters would make a GET URL too long.

Returns the response body as a string.

Package account is used if not defined as second parameter.

http_query(url, data, [account]);

Example:

let url = "/search";
let data = {
  ids: [1, 2, 3],
};
let result = http_query(url, data, "tw");
log("response:", result);

http_post​

Performs an HTTP POST request with data on the URL path appended to the account URL.

Returns the response body as a string.

Package account is used if not defined as second parameter.

http_post(url, data, [account]);

Example:

let url = "/data";
let data = {
  something: "ok",
};
let result = http_post(url, data, "tw");
log("response:", result);

http_put​

Performs an HTTP PUT request with data on the URL path appended to the account URL.

Returns the response body as a string.

Package account is used if not defined as second parameter.

http_put(url, data, [account]);

Example:

let url = "/data";
let data = {
  something: "ok",
};
let result = http_put(url, data, "tw");
log("response:", result);

http_patch​

Performs an HTTP PATCH request with data on the URL path appended to the account URL.

Returns the response body as a string.

Package account is used if not defined as second parameter.

http_patch(url, data, [account]);

Example:

let url = "/data";
let data = {
  something: "ok",
};
let result = http_patch(url, data, "tw");
log("response:", result);

http_request​

Performs a configurable HTTP request. Use http_request for GET, QUERY, POST, PUT, PATCH, or DELETE requests when you need control over headers, authentication, body encoding, or query parameters that the simpler http_get/http_query/http_post/http_put/http_patch functions don't expose.

If no account is given as the second parameter, the package's account is used.

The options.url may be a full URL (starting with http:// or https://) or a path that is appended to the account's base URL.

http_request(options, [account]);

Options​

The options listed below are supported.

  • url — Absolute URL or a path appended to the account's base URL.
  • method — HTTP method: "GET", "QUERY", "POST", "PUT", "PATCH", or "DELETE".
  • headers — Object of header names to values. Merged on top of the account's headers.
  • auth — Optional authentication (overriding the authentication of the account if set). One of:
    • { bearer: "token" } — sends Authorization: Bearer token.
    • { user: "name", pass: "secret" } — sends HTTP Basic authentication.
  • body — Raw request body, as a string or Buffer.
  • json — Object sent as a JSON request body. Adds Content-Type: application/json and parses the response body as JSON.
  • form — Object sent as a URL-encoded request body. Adds Content-Type: application/x-www-form-urlencoded.
  • formData — Object sent as a multipart/form-data request body. Each value may be a string, a Buffer, an array of those, or { value, options: { filename, contentType } } for a file part with a custom filename and content type.
  • qs — Object whose key/value pairs are appended to the URL as a query string.

Use exactly one of body, json, form, or formData per request.

Return value​

http_request returns an object with two fields:

  • body — The response body. A string by default, or the parsed value when options.json is set.
  • response — The response metadata, containing statusCode, statusMessage and headers.

The body is returned for any status code, including 4xx and 5xx — connection errors throw, but HTTP error responses do not.

Example — POST a JSON payload:

let options = {
  url: "/tasks",
  method: "POST",
  json: { title: "New task", priority: "high" },
};

let result = http_request(options, myAccount);
log("created task with id", result.body.id);

Example — multipart upload with a generated PDF:

let pdfBuffer = create_pdf({ content: "Hello World" }, {});

let options = {
  url: "/attachments",
  method: "POST",
  auth: { bearer: "bearer-token" },
  formData: {
    description: "Generated report",
    file: {
      value: pdfBuffer,
      options: { filename: "report.pdf", contentType: "application/pdf" },
    },
  },
};

http_request(options, myAccount);

Example — GET with a query string:

let result = http_request(
  { url: "/tasks", method: "GET", qs: { status: "in_progress" } }
);
log("tasks in progress:", parse(result.body).map(task => task.id));

http_request_file​

Downloads a file via HTTP and returns its content as a Buffer.

If no account is given as the second parameter, the package's account is used.

The options.url may be a full URL (starting with http:// or https://) or a path that is appended to the account's base URL.

http_request_file is for method "GET" only. The maximum file size is 50 MB; larger downloads are aborted and reported via the result's error field.

http_request_file(options, [account]);

Options​

The function http_request_file supports the following options:

  • url — Absolute URL or a path appended to the account's base URL.
  • method — Optional. If specified, it must be "GET".
  • headers — Object of header names to values. Merged on top of the account's headers.
  • auth — Authentication, overriding the account's authentication. Same shape as for http_request: { bearer } or { user, pass }.

Return value​

Returns { content, headers, statusCode, error }:

  • content — The downloaded file as a Buffer, or null on error.
  • headers — The response headers.
  • statusCode — The HTTP status code.
  • error — A string describing the failure, or null on success. Set when the size limit is exceeded or the download stream fails.

Example:

let options = {
  url: "documents/86e99d7e52d/pdf",
  method: "GET",
};

let result = http_request_file(options, "tw");

file_create("file_store", "test.pdf", result.content);

http_stream_file​

Downloads a file via HTTP and streams it directly into a file repository, without buffering the full content in memory. Prefer http_stream_file over http_request_file for large files.

If no account is given as the last parameter, the package's account is used.

The options.url may be a full URL (starting with http:// or https://) or a path that is appended to the account's base URL.

http_stream_file is for method "GET" only. There is no fixed file size limit.

http_stream_file(options, fileRepository, filename, [account]);

Arguments​

  • options — Same option fields as for http_request_file: url, method, headers, auth.
  • fileRepository — Name of the file repository account to write the streamed file into.
  • filename — Name of the file to create in the repository.
  • account — Optional HTTP account; defaults to the package account.

Example:

let options = {
  url: "documents/86e99d7e52d/pdf",
  method: "GET",
};

http_stream_file(options, "streamed_files", "report.pdf", "tw");

query_stringify​

Converts an object into a URL query string.

Returns the query string.

const queryString = query_stringify(object);

Example:

let params = { status: "active", page: 2, limit: 10 };
let qs = query_stringify(params);
log("query:", qs); // => 'status=active&page=2&limit=10'