Awesome
Tesla
Tesla
is an HTTP client that leverages middleware to streamline HTTP requests
and responses over a common interface for various adapters.
It simplifies HTTP communication by providing a flexible and composable
middleware stack. Developers can easily build custom API clients by stacking
middleware components that handle tasks like authentication, logging, and
retries. Tesla
supports multiple HTTP adapters such as Mint
, Finch
,
Hackney
, etc.
Tesla
is ideal for developers who need a flexible and efficient HTTP client.
Its ability to swap out HTTP adapters and create custom middleware pipelines
empowers you to make different architectural decisions and build tools tailored
to your application's needs with minimal effort.
Inspired by Faraday from Ruby.
Getting started
Add :tesla
as dependency in mix.exs
:
defp deps do
[
# or latest version
{:tesla, "~> 1.11"},
# optional, required by JSON middleware
{:jason, "~> 1.4"},
# optional, required by Mint adapter, recommended
{:mint, "~> 1.0"}
]
end
:httpc as default Adapter {: .error}
The default adapter is erlang's built-in
httpc
, primarily to avoid additional dependencies when usingTesla
in a new project. But it is not recommended to use it in production environment as it does not validate SSL certificates among other issues. Instead, consider usingMint
,Finch
, orHackney
adapters. We believe that such security issues should be addressed by:httpc
itself and we are not planning to fix them inTesla
due to backward compatibility.
Configure default adapter in config/config.exs
.
# config/config.exs
# Make sure to install `mint` package as well, recommended
config :tesla, adapter: Tesla.Adapter.Mint
To make a simple GET request, run iex -S mix
and execute:
iex> Tesla.get!("https://httpbin.org/get").status
# => 200
That will not include any middleware and will use the global default adapter. Create a client to compose middleware and reuse it across requests.
iex> client = Tesla.client([
...> {Tesla.Middleware.BaseUrl, "https://httpbin.org/"},
...> Tesla.Middleware.JSON,
...> ])
iex> Tesla.get!(client, "/json").body
# => %{"slideshow" => ...}
Lastly, you can enforce the adapter to be used by a specific client:
iex> client = Tesla.client([], {Tesla.Adapter.Hackney, pool: :my_pool})
Happy hacking!
What to do next?
Check out the following sections to learn more about Tesla
:
Explanations
Howtos
Migrations
References
Middleware
Tesla
is built around the concept of composable middlewares.
Tesla.Middleware.BaseUrl
- set base URL.Tesla.Middleware.Headers
- set request headers.Tesla.Middleware.Query
- set query parameters.Tesla.Middleware.Opts
- set request options.Tesla.Middleware.FollowRedirects
- follow HTTP 3xx redirects.Tesla.Middleware.MethodOverride
- setX-Http-Method-Override
header.Tesla.Middleware.Logger
- log requests (method, url, status, and time).Tesla.Middleware.KeepRequest
- keep requestbody
andheaders
.Tesla.Middleware.PathParams
- use templated URLs.
Formats
Tesla.Middleware.FormUrlencoded
- URL encode POST body, useful for POSTing a map/keyword list.Tesla.Middleware.JSON
- encode/decode JSON request/response body.Tesla.Middleware.Compression
- compress request/response body usinggzip
anddeflate
.Tesla.Middleware.DecodeRels
- decodeLink
header intoopts[:rels]
field in response.
Auth
Tesla.Middleware.BasicAuth
- HTTP Basic Auth.Tesla.Middleware.BearerAuth
- HTTP Bearer Auth.Tesla.Middleware.DigestAuth
] - Digest access authentication.
Error handling
Tesla.Middleware.Timeout
- timeout request after X milliseconds despite of server response.Tesla.Middleware.Retry
- retry few times in case of connection refused.Tesla.Middleware.Fuse
- fuse circuit breaker integration.
Adapters
Tesla supports multiple HTTP adapter that do the actual HTTP request processing.
Tesla.Adapter.Httpc
- the default, built-in Erlang httpc adapter.Tesla.Adapter.Hackney
- hackney, simple HTTP client in Erlang.Tesla.Adapter.Ibrowse
- ibrowse, Erlang HTTP client.Tesla.Adapter.Gun
- gun, HTTP/1.1, HTTP/2 and Websocket client for Erlang/OTP.Tesla.Adapter.Mint
- mint, Functional HTTP client for Elixir with support for HTTP/1 and HTTP/2.Tesla.Adapter.Finch
- finch, An HTTP client with a focus on performance, built on top of Mint and NimblePool.