View Source Req (req v0.3.10)
The high-level API.
Req is composed of three main pieces:
Req
- the high-level API (you're here!)Req.Request
- the low-level API and the request structReq.Steps
- the collection of built-in steps
The high-level API is what most users of Req will use most of the time.
examples
Examples
Making a GET request with Req.get!/1
:
iex> Req.get!("https://api.github.com/repos/wojtekmach/req").body["description"]
"Req is a batteries-included HTTP client for Elixir."
Same, but by explicitly building request struct first:
iex> req = Req.new(base_url: "https://api.github.com")
iex> Req.get!(req, url: "/repos/wojtekmach/req").body["description"]
"Req is a batteries-included HTTP client for Elixir."
Making a POST request with Req.post!/2
:
iex> Req.post!("https://httpbin.org/post", form: [comments: "hello!"]).body["form"]
%{"comments" => "hello!"}
Link to this section Summary
Functions
Returns default options.
Sets default options for Req.new/1
.
Makes a DELETE request.
Makes a DELETE request.
Makes a GET request.
Makes a GET request.
Makes a HEAD request.
Makes a HEAD request.
Returns a new request struct with built-in steps.
Makes a PATCH request.
Makes a PATCH request.
Makes a POST request.
Makes a POST request.
Makes a PUT request.
Makes a PUT request.
Makes an HTTP request.
Makes an HTTP request.
Makes an HTTP request and returns a response or raises an error.
Makes an HTTP request and returns a response or raises an error.
Updates a request struct.
Link to this section Types
Link to this section Functions
@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 new/1
for a list of available 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 new/1
for a list of available 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 new/1
for a list of available options.
examples
Examples
With URL:
iex> {:ok, res} = Req.get("https://api.github.com/repos/wojtekmach/req")
iex> res.body["description"]
"Req is a batteries-included HTTP client for Elixir."
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 new/1
for a list of available options.
examples
Examples
With URL:
iex> Req.get!("https://api.github.com/repos/wojtekmach/req").body["description"]
"Req is a batteries-included HTTP client for Elixir."
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 new/1
for a list of available 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 new/1
for a list of available 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 Req.Request
module documentation for more information on the underlying request struct.
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.
DateTime
header values are encoded as "HTTP date". Otherwise, the header value is encoded withString.Chars.to_string/1
.
If you set
:headers
options both inReq.new/1
andrequest/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 (viaput_base_url
step.):params
- if set, appends parameters to the request query string (viaput_params
step.):path_params
- if set, uses a templated request path (viaput_path_params
step.)
Authentication options:
:auth
- sets request authentication (viaauth
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 frompath
.
:redact_auth
- if set totrue
, whenReq.Request
struct is inspected, authentication credentials are redacted. Defaults totrue
.
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 totrue
, compresses the request body using gzip (viacompress_body
step.) Defaults tofalse
.
Response body options:
:compressed
- if set totrue
, asks the server to return compressed response. (viacompressed
step.) Defaults totrue
.:raw
- if set totrue
, disables automatic body decompression (decompress_body
step) and decoding (decode_body
step.) Defaults tofalse
.:decode_body
- if set tofalse
, disables automatic response body decoding. Defaults totrue
.:decode_json
- options to pass toJason.decode!/2
, defaults to[]
.:output
- if set, writes the response body to a file (viaoutput
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 thedecode_body: false
option to prevent decoding the response before writing it to the file.
Response redirect options (follow_redirects
step):
:follow_redirects
- if set tofalse
, disables automatic response redirects. Defaults totrue
.:location_trusted
- by default, authorization credentials are only sent on redirects with the same host, scheme and port. If:location_trusted
is set totrue
, credentials will be sent to any host.:max_redirects
- the maximum number of redirects, defaults to10
.
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, andfun
- a 1-arity function that accepts either aReq.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 to3
(for a total of4
requests to the server, including the initial one.)
Caching options (cache
step):
:cache
- iftrue
, performs HTTP caching. Defaults tofalse
.: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 theReq.Request
module documentation for more information. Defaults to callingrun_finch
.:plug
- if set, calls the given Plug instead of making an HTTP request over the network (viaput_plug
step).
Finch options (run_finch
step)
:finch
- the Finch pool to use. Defaults to pool automatically started byReq
.:connect_options
- dynamically starts (or re-uses already started) Finch pool with the given connection options::timeout
- socket connect timeout in milliseconds, defaults to30_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 to5000
.:receive_timeout
- socket receive timeout in milliseconds, defaults to15_000
.:unix_socket
- if set, connect through the given UNIX domain socket.:finch_request
- a function that executes the Finch request, defaults to usingFinch.request/3
.
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"
With mock adapter:
iex> mock = fn request ->
...> {request, Req.Response.new(status: 200, body: "it works!")}
...> end
iex>
iex> req = Req.new(adapter: mock)
iex> Req.get!(req).body
"it works!"
@spec patch(url() | Req.Request.t(), options :: keyword()) :: {:ok, Req.Response.t()} | {:error, Exception.t()}
Makes a PATCH request.
See new/1
for a list of available 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 new/1
for a list of available 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 new/1
for a list of available 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 new/1
for a list of available 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 new/1
for a list of available 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 new/1
for a list of available 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.
See new/1
for a list of availale options.
examples
Examples
With options keywords list:
iex> {:ok, response} = Req.request(url: "https://api.github.com/repos/wojtekmach/req")
iex> response.status
200
iex> response.body["description"]
"Req is a batteries-included HTTP client for Elixir."
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
@spec request(Req.Request.t(), options :: keyword()) :: {:ok, Req.Response.t()} | {:error, Exception.t()}
Makes an HTTP request.
See new/1
for a list of availale options.
examples
Examples
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
@spec request!(Req.Request.t() | keyword()) :: Req.Response.t()
Makes an HTTP request and returns a response or raises an error.
See new/1
for a list of available options.
examples
Examples
With options keywords list:
iex> Req.request!(url: "https://api.github.com/repos/elixir-lang/elixir").status
200
With request struct:
iex> req = Req.new(url: "https://api.github.com/repos/elixir-lang/elixir")
iex> Req.request!(req).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 new/1
for a list of available options.
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 new/1
for a list of available options. Also 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"}]