@spec default_options() :: keyword()

Returns default options.

See default_options/1 for more information.

@spec default_options(keyword()) :: :ok

Sets default options for Req.new/1.

Avoid setting default options in libraries as they are global.

Examples

iex> Req.default_options(base_url: "https://httpbin.org")
iex> Req.get!("/statuses/201").status
201
iex> Req.new() |> Req.get!(url: "/statuses/201").status
201

@spec merge(Req.Request.t(), options :: keyword()) :: Req.Request.t()

Updates a request struct.

See new/1 for a list of available options. Also see Req.Request module documentation for more information on the underlying request struct.

Examples

iex> req = Req.new(base_url: "https://httpbin.org")
iex> req = Req.merge(req, auth: {:basic, "alice:secret"})
iex> req.options[:base_url]
"https://httpbin.org"
iex> req.options[:auth]
{:basic, "alice:secret"}

Passing :headers will automatically encode and merge them:

iex> req = Req.new(headers: %{point_x: 1})
iex> req = Req.merge(req, headers: %{point_y: 2})
iex> req.headers
%{"point-x" => ["1"], "point-y" => ["2"]}

The same header names are overwritten however:

iex> req = Req.new(headers: %{authorization: "bearer foo"})
iex> req = Req.merge(req, headers: %{authorization: "bearer bar"})
iex> req.headers
%{"authorization" => ["bearer bar"]}

Similarly to headers, :params are merged too:

req = Req.new(url: "https://httpbin.org/anything", params: [a: 1, b: 1])
req = Req.merge(req, params: [a: 2])
Req.get!(req).body["args"]
#=> %{"a" => "2", "b" => "1"}

@spec new(options :: keyword()) :: Req.Request.t()

Returns a new request struct with built-in steps.

See request/2, run/2, as well as get/2, post/2, and similar functions for making requests.

Also see Req.Request module documentation for more information on the underlying request struct.

Options

Basic request options:

• :method - the request method, defaults to :get.

• :url - the request URL.

• :headers - the request headers as a {key, value} enumerable (e.g. map, keyword list).

  The header names should be downcased.

  The headers are automatically encoded using these rules:

  • atom header names are turned into strings, replacing _ with -. For example, :user_agent becomes "user-agent".

  • string header names are downcased.

  • %DateTime{} header values are encoded as "HTTP date".

  If you set :headers options both in Req.new/1 and request/2, the header lists are merged.

  See also "Header Names" section in the module documentation.

• :body - the request body.

  Can be one of:

  • iodata - send request body eagerly

  • enumerable - stream enumerable as request body

Additional URL options:

• :base_url - if set, the request URL is prepended with this base URL (via put_base_url step.)

• :params - if set, appends parameters to the request query string (via put_params step.)

• :path_params - if set, uses a templated request path (via put_path_params step.)

• :path_params_style (available since v0.5.1) - how path params are expressed (via put_path_params step). Can be one of:

  • :colon - (default) for Plug-style parameters, such as :code in https://httpbin.org/status/:code.

  • :curly - for OpenAPI-style parameters, such as {code} in https://httpbin.org/status/{code}.

Authentication options:

• :auth - sets request authentication (via auth step.)

  Can be one of:

  • {:basic, userinfo} - uses Basic HTTP authentication.

  • {:bearer, token} - uses Bearer HTTP authentication.

  • :netrc - load credentials from the default .netrc file.

  • {:netrc, path} - load credentials from path.

  • string - sets to this value.

  • &fun/0 - a function that returns one of the above (such as a {:bearer, token}).

Request body encoding options (encode_body):

• :form - if set, encodes the request body as application/x-www-form-urlencoded

• :form_multipart - if set, encodes the request body as multipart/form-data.

• :json - if set, encodes the request body as JSON

Other request body options:

• :compress_body - if set to true, compresses the request body using gzip (via compress_body step.) Defaults to false.

AWS Signature Version 4 options (put_aws_sigv4 step):

• :aws_sigv4 - if set, the AWS options to sign request:

  • :access_key_id - the AWS access key id.

  • :secret_access_key - the AWS secret access key.

  • :service - the AWS service.

  • :region - if set, AWS region. Defaults to "us-east-1".

  • :datetime - the request datetime, defaults to DateTime.utc_now(:second).

Response body options:

• :compressed - if set to true, asks the server to return compressed response. (via compressed step.) Defaults to true.

• :raw - if set to true, disables automatic body decompression (decompress_body step) and decoding (decode_body step.) Defaults to false.

• :decode_body - if set to false, disables automatic response body decoding. Defaults to true.

• :decode_json - options to pass to Jason.decode!/2, defaults to [].

• :into - where to send the response body. It can be one of:

  • nil - (default) read the whole response body and store it in the response.body field.

  • fun - stream response body using a function. The first argument is a {:data, data} tuple containing the chunk of the response body. The second argument is a {request, response} tuple. To continue streaming chunks, return {:cont, {req, resp}}. To cancel, return {:halt, {req, resp}}. For example:

    into: fn {:data, data}, {req, resp} ->
      IO.puts(data)
      {:cont, {req, resp}}
    end

  • collectable - stream response body into a Collectable.t/0. For example:

     into: File.stream!("path")

    Note that the collectable is only used, if the response status is 200. In other cases, the body is accumulated and processed as usual.

  • :self - stream response body into the current process mailbox.

    Received messages should be parsed with Req.parse_message/2.

    response.body is set to opaque data structure Req.Response.Async which implements Enumerable that receives and automatically parses messages. See module documentation for example usage.

    If the request is sent using HTTP/1, an extra process is spawned to consume messages from the underlying socket. On both HTTP/1 and HTTP/2 the messages are sent to the current process as soon as they arrive, as a firehose. If you wish to maximize request rate or have more control over how messages are streamed, use into: fun or into: collectable instead.

Response redirect options (redirect step):

• :redirect - if set to false, disables automatic response redirects. Defaults to true.

• :redirect_trusted - by default, authorization credentials are only sent on redirects with the same host, scheme and port. If :redirect_trusted is set to true, credentials will be sent to any host.

• :max_redirects - the maximum number of redirects, defaults to 10.

Retry options (retry step):

• :retry - can be one of the following:

  • :safe_transient (default) - retry safe (GET/HEAD) requests on one of:

    • HTTP 408/429/500/502/503/504 responses

    • Req.TransportError with reason: :timeout | :econnrefused | :closed

    • Req.HTTPError with protocol: :http2, reason: :unprocessed

  • :transient - same as :safe_transient except retries all HTTP methods (POST, DELETE, etc.)

  • fun - a 2-arity function that accepts a Req.Request and either a Req.Response or an exception struct and returns one of the following:

    • true - retry with the default delay controller by default delay option described below.

    • {:delay, milliseconds} - retry with the given delay.

    • false/nil - don't retry.

  • false - don't retry.

• :retry_delay - if not set, which is the default, the retry delay is determined by the value of the Retry-After header on HTTP 429/503 responses. If the header is not set, the default delay follows a simple exponential backoff: 1s, 2s, 4s, 8s, ...

  :retry_delay can be set to a function that receives the retry count (starting at 0) and returns the delay, the number of milliseconds to sleep before making another attempt.

• :retry_log_level - the log level to emit retry logs at. Can also be set to false to disable logging these messages. Defaults to :warning.

• :max_retries - maximum number of retry attempts, defaults to 3 (for a total of 4 requests to the server, including the initial one.)

Caching options (cache step):

• :cache - if true, performs HTTP caching. Defaults to false.

• :cache_dir - the directory to store the cache, defaults to <user_cache_dir>/req (see: :filename.basedir/3)

Request adapters:

• :adapter - adapter to use to make the actual HTTP request. See :adapter field description in the Req.Request module documentation for more information.

  The default is run_finch.

• :plug - if set, calls the given plug instead of making an HTTP request over the network (via run_plug step).

  The plug can be one of:

  • A function plug: a fun(conn) or fun(conn, options) function that takes a Plug.Conn and returns a Plug.Conn.

  • A module plug: a module name or a {module, options} tuple.

Finch options (run_finch step)

• :finch - the Finch pool to use. Defaults to pool automatically started by Req.

• :connect_options - dynamically starts (or re-uses already started) Finch pool with the given connection options:

  • :timeout - socket connect timeout in milliseconds, defaults to 30_000.

  • :protocols - the HTTP protocols to use, defaults to [:http1].

  • :hostname - Mint explicit hostname.

  • :transport_opts - Mint transport options.

  • :proxy_headers - Mint proxy headers.

  • :proxy - Mint HTTP/1 proxy settings, a {schema, address, port, options} tuple.

  • :client_settings - Mint HTTP/2 client settings.

• :inet6 - if set to true, uses IPv6. Defaults to false.

• :pool_timeout - pool checkout timeout in milliseconds, defaults to 5000.

• :receive_timeout - socket receive timeout in milliseconds, defaults to 15_000.

• :unix_socket - if set, connect through the given UNIX domain socket.

• :pool_max_idle_time - the maximum number of milliseconds that a pool can be idle before being terminated, used only by HTTP1 pools. Default to :infinity.

• :finch_private - a map or keyword list of private metadata to add to the Finch request. May be useful for adding custom data when handling telemetry with Finch.Telemetry.

• :finch_request - a function that executes the Finch request, defaults to using Finch.request/3.

Examples

iex> req = Req.new(url: "https://elixir-lang.org")
iex> req.method
:get
iex> URI.to_string(req.url)
"https://elixir-lang.org"

Fake adapter:

iex> fake = fn request ->
...>   {request, Req.Response.new(status: 200, body: "it works!")}
...> end
iex>
iex> req = Req.new(adapter: fake)
iex> Req.get!(req).body
"it works!"