http

HTTP client.

The module-level request functions -- get, post and the rest -- each make one request through a fresh stateless client. Anything that has to persist across requests (cookies, a proxy, TLS material) belongs on a Client, whose methods take the same arguments.

Every URL argument accepts either a plain Str or a url.Url.

let data = get https://api.example.com/users
  query: {page: 1}
  headers: {authorization: "Bearer $token"}

Browser

Browser builds, such as the playground, send requests through fetch:

• Cross-origin requests succeed only against servers that send CORS headers, and only CORS-exposed response headers are visible.
• The browser controls forbidden headers such as Cookie, Host and User-Agent, and cookies follow its credentials rules.
• Request bodies are buffered, not streamed.
• The Client options unix_socket, proxy, cookies, ca_cert, identity, password and invalid_certs raise RuntimeError.

Types

Type	Description
Client	An HTTP client.
Error	A transport or protocol failure.
Event	One item of a Server-Sent Events stream.
Response	An HTTP response.
Status	A response whose status is outside 200..=299.
BodyOptions	Options of a request with a body: those of RequestOptions, and at most one of these.
RequestOptions	Options of a request, which every request function and Client method takes.

BodyOptions

Options of a request with a body: those of RequestOptions, and at most one of these.

Item	Type	Description
...	RequestOptions	Any of RequestOptions
?body	Str | Bin | io.Io | Iterable[Value]	Request body -- see body
?json	json.EncodeValue	Request body, JSON-serialized -- see json
?lines	Iterable[Value]	Request body streamed with a newline after each element -- see lines
?multipart	Iterable[Dict[{name: Str, ...}]]	Multipart form parts -- see multipart

RequestOptions

Options of a request, which every request function and Client method takes.

Item	Type	Description
?headers	BaseDict[Value, Value]	Request headers -- see headers
?query	BaseDict[Value, Value]	Query parameters -- see query
?status	:IGNORE: | "IGNORE"	:IGNORE: to return a response whose status is outside 200..=299 instead of raising Status

Functions

connect url ...options -> Response ^{overload 1 of 2}

Makes a CONNECT request through a fresh stateless client, as get does.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	RequestOptions	Request options.

connect[R] url ...options block -> R ^{overload 2 of 2}

Makes a CONNECT request through a fresh stateless client and calls block with the response, as get does.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	RequestOptions	Request options.
block	((Response) -> R)	Called with the Response.

delete url ...options -> Response ^{overload 1 of 2}

Makes a DELETE request through a fresh stateless client, as get does.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	RequestOptions	Request options.

delete[R] url ...options block -> R ^{overload 2 of 2}

Makes a DELETE request through a fresh stateless client and calls block with the response, as get does.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	RequestOptions	Request options.
block	((Response) -> R)	Called with the Response.

get url ...options -> Response ^{overload 1 of 2}

Makes a GET request through a fresh stateless client.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	RequestOptions	Request options.

Errors

Exception	Condition
Status	The response is non-2xx and status: was not passed
Error	A transport or protocol failure

Example

get https://api.example.com/users do |response|
  echo $response.status

get[R] url ...options block -> R ^{overload 2 of 2}

Makes a GET request through a fresh stateless client and calls block with the response. The response is closed when block returns.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	RequestOptions	Request options.
block	((Response) -> R)	Called with the Response.

head url ...options -> Response ^{overload 1 of 2}

Makes a HEAD request through a fresh stateless client, as get does.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	RequestOptions	Request options.

head[R] url ...options block -> R ^{overload 2 of 2}

Makes a HEAD request through a fresh stateless client and calls block with the response, as get does.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	RequestOptions	Request options.
block	((Response) -> R)	Called with the Response.

options url ...options -> Response ^{overload 1 of 2}

Makes an OPTIONS request through a fresh stateless client, as get does.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	RequestOptions	Request options.

options[R] url ...options block -> R ^{overload 2 of 2}

Makes an OPTIONS request through a fresh stateless client and calls block with the response, as get does.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	RequestOptions	Request options.
block	((Response) -> R)	Called with the Response.

patch url ...options -> Response ^{overload 1 of 2}

Makes a PATCH request through a fresh stateless client, as post does.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	BodyOptions	Request options.

patch[R] url ...options block -> R ^{overload 2 of 2}

Makes a PATCH request through a fresh stateless client and calls block with the response, as post does.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	BodyOptions	Request options.
block	((Response) -> R)	Called with the Response.

post url ...options -> Response ^{overload 1 of 2}

Makes a POST request through a fresh stateless client.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	BodyOptions	Request options.

Errors

Exception	Condition
Status	The response is non-2xx and status: was not passed
Error	A transport or protocol failure

Example

post https://api.example.com/users
  json: {name: "Alice"}

post[R] url ...options block -> R ^{overload 2 of 2}

Makes a POST request through a fresh stateless client and calls block with the response. The response is closed when block returns.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	BodyOptions	Request options.
block	((Response) -> R)	Called with the Response.

put url ...options -> Response ^{overload 1 of 2}

Makes a PUT request through a fresh stateless client, as post does.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	BodyOptions	Request options.

put[R] url ...options block -> R ^{overload 2 of 2}

Makes a PUT request through a fresh stateless client and calls block with the response, as post does.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	BodyOptions	Request options.
block	((Response) -> R)	Called with the Response.

trace url ...options -> Response ^{overload 1 of 2}

Makes a TRACE request through a fresh stateless client, as get does.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	RequestOptions	Request options.

trace[R] url ...options block -> R ^{overload 2 of 2}

Makes a TRACE request through a fresh stateless client and calls block with the response, as get does.

Parameters

Name	Type	Description
url	(Str | url.Url)	URL to request.
...options	RequestOptions	Request options.
block	((Response) -> R)	Called with the Response.