@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

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 delete(url() | Req.Request.t(), options :: keyword()) ::
  {:ok, Req.Response.t()} | {:error, Exception.t()}

Makes a DELETE request.

See request/1 for a list of supported options.

examples

Examples

With URL:

iex> {:ok, res} = Req.delete("https://httpbin.org/anything")
iex> res.body["method"]
"DELETE"

With request struct:

iex> req = Req.new(url: "https://httpbin.org/anything")
iex> {:ok, res} = Req.delete(req)
iex> res.body["method"]
"DELETE"

@spec delete!(url() | Req.Request.t(), options :: keyword()) :: Req.Response.t()

Makes a DELETE request.

See request/1 for a list of supported options.

examples

Examples

With URL:

iex> Req.delete!("https://httpbin.org/anything").body["method"]
"DELETE"

With request struct:

iex> req = Req.new(url: "https://httpbin.org/anything")
iex> Req.delete!(req).body["method"]
"DELETE"

@spec get(url() | Req.Request.t(), options :: keyword()) ::
  {:ok, Req.Response.t()} | {:error, Exception.t()}

Makes a GET request.

See request/1 for a list of supported options.

examples

Examples

With URL:

iex> {:ok, res} = Req.get("https://api.github.com/repos/elixir-lang/elixir")
iex> res.body["description"]
"Elixir is a dynamic, functional language designed for building scalable and maintainable applications"

With request struct:

iex> req = Req.new(base_url: "https://api.github.com")
iex> {:ok, res} = Req.get(req, url: "/repos/elixir-lang/elixir")
iex> res.status
200

@spec get!(url() | Req.Request.t(), options :: keyword()) :: Req.Response.t()

Makes a GET request.

See request/1 for a list of supported options.

examples

Examples

With URL:

iex> Req.get!("https://api.github.com/repos/elixir-lang/elixir").body["description"]
"Elixir is a dynamic, functional language designed for building scalable and maintainable applications"

With request struct:

iex> req = Req.new(base_url: "https://api.github.com")
iex> Req.get!(req, url: "/repos/elixir-lang/elixir").status
200

@spec head(url() | Req.Request.t(), options :: keyword()) :: Req.Response.t()

Makes a HEAD request.

See request/1 for a list of supported options.

examples

Examples

With URL:

iex> {:ok, res} = Req.head("https://httpbin.org/status/201")
iex> res.status
201

With request struct:

iex> req = Req.new(base_url: "https://httpbin.org")
iex> {:ok, res} = Req.head(req, url: "/status/201")
iex> res.status
201

@spec head!(url() | Req.Request.t(), options :: keyword()) :: Req.Response.t()

Makes a HEAD request.

See request/1 for a list of supported options.

examples

Examples

With URL:

iex> Req.head!("https://httpbin.org/status/201").status
201

With request struct:

iex> req = Req.new(base_url: "https://httpbin.org")
iex> Req.head!(req, url: "/status/201").status
201

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

Returns a new request struct with built-in steps.

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

examples

Examples

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

@spec patch(url() | Req.Request.t(), options :: keyword()) ::
  {:ok, Req.Response.t()} | {:error, Exception.t()}

Makes a PATCH request.

See request/1 for a list of supported options.

examples

Examples

With URL:

iex> {:ok, res} = Req.patch("https://httpbin.org/anything", body: "hello!")
iex> res.body["data"]
"hello!"

With request struct:

iex> req = Req.new(url: "https://httpbin.org/anything")
iex> {:ok, res} = Req.patch(req, body: "hello!")
iex> res.body["data"]
"hello!"

@spec patch!(url() | Req.Request.t(), options :: keyword()) :: Req.Response.t()

Makes a PATCH request.

See request/1 for a list of supported options.

examples

Examples

With URL:

iex> Req.patch!("https://httpbin.org/anything", body: "hello!").body["data"]
"hello!"

With request struct:

iex> req = Req.new(url: "https://httpbin.org/anything")
iex> Req.patch!(req, body: "hello!").body["data"]
"hello!"

@spec post(url() | Req.Request.t(), options :: keyword()) ::
  {:ok, Req.Response.t()} | {:error, Exception.t()}

Makes a POST request.

See request/1 for a list of supported options.

examples

Examples

With URL:

iex> {:ok, res} = Req.post("https://httpbin.org/anything", body: "hello!")
iex> res.body["data"]
"hello!"

iex> {:ok, res} = Req.post("https://httpbin.org/anything", form: [x: 1])
iex> res.body["form"]
%{"x" => "1"}

iex> {:ok, res} = Req.post("https://httpbin.org/anything", json: %{x: 2})
iex> res.body["json"]
%{"x" => 2}

With request struct:

iex> req = Req.new(url: "https://httpbin.org/anything")
iex> {:ok, res} = Req.post(req, body: "hello!")
iex> res.body["data"]
"hello!"

@spec post!(url() | Req.Request.t(), options :: keyword()) :: Req.Response.t()

Makes a POST request.

See request/1 for a list of supported options.

examples

Examples

With URL:

iex> Req.post!("https://httpbin.org/anything", body: "hello!").body["data"]
"hello!"

iex> Req.post!("https://httpbin.org/anything", form: [x: 1]).body["form"]
%{"x" => "1"}

iex> Req.post!("https://httpbin.org/anything", json: %{x: 2}).body["json"]
%{"x" => 2}

With request struct:

iex> req = Req.new(url: "https://httpbin.org/anything")
iex> Req.post!(req, body: "hello!").body["data"]
"hello!"

@spec put(url() | Req.Request.t(), options :: keyword()) ::
  {:ok, Req.Response.t()} | {:error, Exception.t()}

Makes a PUT request.

See request/1 for a list of supported options.

examples

Examples

With URL:

iex> {:ok, res} = Req.put("https://httpbin.org/anything", body: "hello!")
iex> res.body["data"]
"hello!"

With request struct:

iex> req = Req.new(url: "https://httpbin.org/anything")
iex> {:ok, res} = Req.put(req, body: "hello!")
iex> res.body["data"]
"hello!"

@spec put!(url() | Req.Request.t(), options :: keyword()) :: Req.Response.t()

Makes a PUT request.

See request/1 for a list of supported options.

examples

Examples

With URL:

iex> Req.put!("https://httpbin.org/anything", body: "hello!").body["data"]
"hello!"

With request struct:

iex> req = Req.new(url: "https://httpbin.org/anything")
iex> Req.put!(req, body: "hello!").body["data"]
"hello!"

@spec request(Req.Request.t() | keyword()) ::
  {:ok, Req.Response.t()} | {:error, Exception.t()}

Makes an HTTP request.

request/1 and request/2 functions give three ways of making requests:

1. With a list of options, for example:

   iex> Req.request(url: url)

2. With a request struct, for example:

   iex> Req.new(url: url) |> Req.request()

3. With a request struct and more options, for example:

   iex> Req.new(base_url: base_url) |> Req.request(url: url)

This function as well as all the other ones in this module accept the same set of options described below.

options

Options

Basic request options:

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

• :url - the request URL.

• :headers - the request headers.

  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 left as is. Because header keys are case-insensitive in both HTTP/1.1 and HTTP/2, it is recommended for header keys to be in lowercase, to avoid sending duplicate keys in a request.

  • NaiveDateTime and DateTime header values are encoded as "HTTP date". Otherwise, the header value is encoded with String.Chars.to_string/1.

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

• :body - the 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).

Authentication options:

• :auth - sets request authentication (via auth step). Can be one of:

  • string - sets to this value;

  • {username, password} - uses Basic HTTP authentication;

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

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

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

Request body options:

• :form - if set, encodes the request body as form data (encode_body step).

• :json - if set, encodes the request body as JSON (encode_body step).

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

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.

• :extract - if set to a path, extracts archives (tar, zip, etc) into the given directory and sets the response body to the list of extracted filenames.

• :output - if set, writes the response body to a file (via output step). Can be set to a string path or an atom :remote_name which would use the remote name as the filename in the current working directory. Once the file is written, the response body is replaced with "".

  Setting :output also sets the decode_body: false option to prevent decoding the response before writing it to the file.

Response redirect options (follow_redirects step):

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

• :location_trusted - by default, authorization credentials are only sent on redirects with the same host, scheme and port. If :location_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 set to: :safe (default) to only retry GET/HEAD requests on HTTP 408/5xx responses or exceptions, false to never retry, and fun - a 1-arity function that accepts either a Req.Response or an exception struct and returns boolean whether to retry

• :retry_delay - a function that receives the retry count (starting at 0) and returns the delay, the number of milliseconds to sleep before making another attempt. Defaults to a simple exponential backoff: 1s, 2s, 4s, 8s, ...

• :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. Defaults to calling run_finch.

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

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.

  • :protocol - the HTTP protocol 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

• :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

• :finch_request - a function to modify the built Finch request before execution. This function takes a Finch request and returns a Finch request. If not provided, the finch request will not be modified

examples

Examples

With options keywords list:

iex> {:ok, response} = Req.request(url: "https://api.github.com/repos/elixir-lang/elixir")
iex> response.status
200
iex> response.body["description"]
"Elixir is a dynamic, functional language designed for building scalable and maintainable applications"

With request struct:

iex> req = Req.new(url: "https://api.github.com/repos/elixir-lang/elixir")
iex> {:ok, response} = Req.request(req)
iex> response.status
200

With request struct and options:

iex> req = Req.new(base_url: "https://api.github.com")
iex> {:ok, response} = Req.request(req, url: "/repos/elixir-lang/elixir")
iex> response.status
200

With mock adapter:

iex> adapter = fn request ->
...>   response = %Req.Response{status: 200, body: "it works!"}
...>   {request, response}
...> end
iex>
iex> {:ok, response} = Req.request(adapter: adapter, url: "http://example")
iex> response.body
"it works!"

@spec request(Req.Request.t(), options :: keyword()) ::
  {:ok, Req.Response.t()} | {:error, Exception.t()}

Makes an HTTP request.

See request/1 for more information.

@spec request!(Req.Request.t() | keyword()) :: Req.Response.t()

Makes an HTTP request and returns a response or raises an error.

See request/1 for more information.

examples

Examples

iex> Req.request!(url: "https://api.github.com/repos/elixir-lang/elixir").status
200

@spec request!(Req.Request.t(), options :: keyword()) :: Req.Response.t()

Makes an HTTP request and returns a response or raises an error.

See request/1 for more information.

examples

Examples

iex> req = Req.new(base_url: "https://api.github.com")
iex> Req.request!(req, url: "/repos/elixir-lang/elixir").status
200

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

Updates a request struct.

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

examples

Examples

iex> req = Req.new(base_url: "https://httpbin.org")
iex> req = Req.update(req, auth: {"alice", "secret"})
iex> req.options
%{auth: {"alice", "secret"}, base_url: "https://httpbin.org"}

Passing :headers will automatically encode and merge them:

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