Reference · HTTP client

http.request

http.request(str, str, any=, map | null=, map | null=) -> map | error(str)

What it does

Sends a request with any method: the method first, then the URL, a body, a map of headers and a map of options (redirects, public_only, cache for GET, timeout, ca, cert, key). The answer is a map { status, ok, headers, body, json }, as http.get gives. The method is upper-cased; the body is sent as http.post sends one: text as text/plain, HTML as text/html, other values as JSON, null nothing. A 307 or 308 after a method other than GET or HEAD is followed with the same method and body.

Examples

http.request("PUT", url, body, { authorization: `Bearer ${token}` })http.request("HEAD", url)                       // the headers alone, body ""http.request("PROPFIND", url, null, { depth: "1" })http.request("OPTIONS", url, null, {}, { timeout: 3 })

print(http.request("get", "http://127.0.0.1:9/"))print(http.request("PROPFIND", "not a url"))

err("http: http://127.0.0.1:9/: Connection Failed: Connect error: Connection refused (os error 111)")err("http: not an http(s) URL: not a url")

Edge cases

• The method is any word, in either case: "get" is sent as GET.
• cache is allowed only when the method is GET; with another it is a runtime error.
• A body on a GET or a DELETE is sent when given; http.get and http.delete take none.
• A method the server does not know is answered with a 405 or 501, an answer with ok false.
• Under a policy with [http] hosts or private = false, and with public_only, the address and each redirect are judged as for http.get; a 303, or a 301 or 302 after a POST, goes on as a GET with no body, as a browser does. To another origin, only the accept, accept-language, content-type and user-agent headers go on.

print(http.request("delete", "http://127.0.0.1:9/items/1", { reason: "spam" }))print(http.request("GET", "http://127.0.0.1:9/", null, null, { cache: 60 }))

err("http: http://127.0.0.1:9/items/1: Connection Failed: Connect error: Connection refused (os error 111)")err("http: http://127.0.0.1:9/: Connection Failed: Connect error: Connection refused (os error 111)")

Errors

A method that is not a string, a URL that is not one, headers that are not a map and an unknown option are runtime errors; not reaching the server is an error value.

let r = http.request("POST", "http://127.0.0.1:9/")print(is_err(r), r.error)

true http: http://127.0.0.1:9/: Connection Failed: Connect error: Connection refused (os error 111)

print(http.request(1, "http://127.0.0.1:9/"))

line 1: `http.request` expects a method string first, got int

print(http.request("POST", "http://127.0.0.1:9/", {}, {}, { cache: 10 }))

line 1: `http.request`: `cache` keeps the answers of GET requests, not POST

Chaining

The method comes first, so a pipeline passes the method, not the URL: write the call out. ? passes an error value on to the caller.

fn call(method: str, path: str, body: any = null) with http {    http.request(method, `${base}${path}`, body, { authorization: key }, { timeout: 10 })?}

print(["GET", "DELETE"] | map((m) => http.request(m, "http://127.0.0.1:9/") | is_err))

[true, true]

See also

http.get, http.post, http.put, http.patch, http.delete, http.stream

Edit this page on GitHub · every example's output was made by running it (tools/refcheck.mjs) · questions on Discord or r/quillo