Req is a batteries-included HTTP client for Elixir.
(Note: This is the README for the current main branch. See README for Req v0.2.2)
-
An easy to use high-level API in
Req
module:request/1
,request!/1
,get!/2
,head!/2
,post!/2
,put!/2
,patch!/2
, anddelete!/2
-
Extensibility via request, response, and error steps
-
Request body compression and automatic response body decompression (via
compress_body
,compressed
, anddecompress_body
steps). Supports gzip, deflate, brotli and zstd decompression. -
Request body encoding and automatic response body decoding (via
encode_body
anddecode_body
steps) -
Encode params as query string (via
put_params
step) -
Basic, bearer, and
.netrc
authentication (viaauth
step) -
Range requests (via
put_range
) step) -
Follows redirects (via
follow_redirects
step) -
Retries on errors (via
retry
step) -
Raise on 4xx/5xx errors (via
handle_http_errors
step) -
Basic HTTP caching (via
cache
step) -
Setting base URL (via
put_base_url
step) -
Running against a plug (via
put_plug
step) -
Pluggable adapters. By default, Req uses Finch (via
run_finch
step).
The easiest way to use Req is with Mix.install/2
(requires Elixir v1.12+):
Mix.install([
{:req, github: "wojtekmach/req"}
])
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"
If you want to use Req in a Mix project, you can add the above dependency to your mix.exs
.
If you are planning to make several similar requests, you can build up a request struct with desired common options and re-use it:
req = Req.new(base_url: "https://api.github.com")
Req.get!(req, url: "/repos/sneako/finch").body["description"]
#=> "Elixir HTTP client, focused on performance"
Req.get!(req, url: "/repos/elixir-mint/mint").body["description"]
#=> "Functional HTTP client for Elixir with support for HTTP/1 and HTTP/2."
See Req.request/1
for more information on available
options.
Virtually all of Req's features are broken down into individual pieces - steps. Req works by running the request struct through these steps. You can easily reuse or rearrange built-in steps or write new ones. Importantly, steps are just regular functions. Here is another example where we append a request step that inspects the URL just before requesting it:
req =
Req.new(base_url: "https://api.github.com")
|> Req.Request.append_request_steps(
debug_url: fn request ->
IO.inspect(URI.to_string(request.url))
request
end
)
Req.get!(req, url: "/repos/wojtekmach/req").body["description"]
# Outputs: "https://api.github.com/repos/wojtekmach/req"
#=> "Req is a batteries-included HTTP client for Elixir."
Custom steps can be packaged into plugins so that they are even easier to use by others. Here are some examples:
And here is how they can be used:
Mix.install([
{:req, github: "wojtekmach/req"},
{:req_easyhtml, github: "wojtekmach/req_easyhtml"},
{:req_s3, github: "wojtekmach/req_s3"},
{:req_hex, github: "wojtekmach/req_hex"},
{:req_github_oauth, github: "wojtekmach/req_github_oauth"}
])
req =
(Req.new(http_errors: :raise)
|> ReqEasyHTML.attach()
|> ReqS3.attach()
|> ReqHex.attach()
|> ReqGitHubOAuth.attach())
Req.get!(req, url: "https://elixir-lang.org").body[".entry-summary h5"]
#=>
# #EasyHTML[<h5>
# Elixir is a dynamic, functional language for building scalable and maintainable applications.
# </h5>]
Req.get!(req, url: "s3://ossci-datasets").body
#=>
# [
# "mnist/",
# "mnist/t10k-images-idx3-ubyte.gz",
# "mnist/t10k-labels-idx1-ubyte.gz",
# "mnist/train-images-idx3-ubyte.gz",
# "mnist/train-labels-idx1-ubyte.gz"
# ]
Req.get!(req, url: "https://repo.hex.pm/tarballs/req-0.1.0.tar").body["metadata.config"]["links"]
#=> %{"GitHub" => "https://github.com/wojtekmach/req"}
Req.get!(req, url: "https://api.github.com/user").body["login"]
# Outputs:
# paste this user code:
#
# 6C44-30A8
#
# at:
#
# https://github.com/login/device
#
# open browser window? [Yn]
# 15:22:28.350 [info] response: authorization_pending
# 15:22:33.519 [info] response: authorization_pending
# 15:22:38.678 [info] response: authorization_pending
#=> "wojtekmach"
Req.get!(req, url: "https://api.github.com/user").body["login"]
#=> "wojtekmach"
See Req.Request
module documentation for
more information on low-level API, request struct, and developing plugins.
Req is built on top of Finch and is inspired by cURL, Requests, Tesla, and many other HTTP clients - thank you!
Copyright (c) 2021 Wojtek Mach
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.