HTTP Class

Perform an HTTP GET request. Returns a Future that resolves to the response body as a string.

resp = HTTP.get("https://api.example.com/users")
if resp["status"] == 200
  println(resp["body"])
end

# Request headers ride along in the options hash.
me = HTTP.get("https://api.example.com/me", {
  "headers": { "Authorization": "Bearer " + token, "X-Client": "soli" }
})

# Per-call timeout in seconds (overrides the 30s default for this request).
resp = HTTP.get("https://api.example.com/slow", { "timeout": 5 })

Fetch a JSONP endpoint and unwrap the callback(...) padding, returning the parsed value. Use it to consume legacy cross-origin APIs that only expose JSONP; put the ?callback=... name in the URL you pass.

feed = HTTP.get_jsonp("https://api.example.com/feed?callback=cb")
println(feed["items"][0])

Perform an HTTP POST request with a body. A hash body is sent as JSON, a string body as text/plain; a Content-Type in options.headers replaces that default.

resp = HTTP.post(
  "https://api.example.com/users",
  "name=Alice",
  { "headers": { "Content-Type": "application/x-www-form-urlencoded" } }
)

Perform an HTTP PUT request with a body.

resp = HTTP.put(
  "https://api.example.com/users/1",
  { "name": "Alice Updated" }
)

Perform an HTTP DELETE request.

resp = HTTP.delete("https://api.example.com/users/1")

Perform an HTTP PATCH request with a body.

resp = HTTP.patch(
  "https://api.example.com/users/1",
  { "email": "new_email@example.com" }
)

Perform an HTTP HEAD request.

resp = HTTP.head("https://api.example.com/users")
println(resp["headers"])

Fetch a URL and write the body to a file, returning the number of bytes written. The one method here that does not decode: every other call ends in UTF-8, which a picture, a sound or a PDF is not. Same SSRF check, same SOLI_HTTP_MAX_RESPONSE_BYTES cap, and the path goes through the same jail as the File builtins — a missing parent directory is created, an escaping path is refused, and a symlink standing where the file should go is not followed. Blocking: it returns when the file is on disk.

bytes = HTTP.download("https://example.com/cover.jpg", "public/covers/1.jpg")
println("wrote " + str(bytes))

GET request with automatic JSON parsing of response body. Sends Accept: application/json unless options.headers overrides it.

data = HTTP.get_json("https://api.example.com/users/1")
println(data["body"]["name"])

# Authenticated, with a 10-second budget.
me = HTTP.get_json("https://api.example.com/me", {
  "headers": { "Authorization": "Bearer " + token },
  "timeout": 10
})

POST request with automatic JSON serialization.

resp = HTTP.post_json(
  "https://api.example.com/users",
  { "name": "Alice", "email": "alice@example.com" }
)

PUT request with automatic JSON serialization.

resp = HTTP.put_json(
  "https://api.example.com/users/1",
  { "name": "Alice Updated", "email": "alice_updated@example.com" }
)

PATCH request with automatic JSON serialization.

resp = HTTP.patch_json(
  "https://api.example.com/users/1",
  { "email": "new_email@example.com" }
)

Perform any HTTP method (GET, POST, PUT, PATCH, DELETE, etc.). The headers hash accepts a timeout key (seconds) that is consumed as the per-call timeout rather than sent as a header.

resp = HTTP.request("DELETE", "https://api.example.com/users/1")
resp = HTTP.request("PATCH", url, headers, json)

# Custom header plus a 3-second per-call timeout.
resp = HTTP.request("GET", url, { "Authorization": "Bearer " + token, "timeout": 3 })