Skip to main content

HTTP

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

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_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, POST, PUT, PATCH, or DELETE requests when you need control over headers, authentication, body encoding, or query parameters that the simpler http_get/ 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", "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'