tesla

# Tesla

[![CI](https://github.com/elixir-tesla/tesla/actions/workflows/ci.yaml/badge.svg)](https://github.com/elixir-tesla/tesla/actions/workflows/ci.yaml)
[![Hex.pm](https://img.shields.io/hexpm/v/tesla.svg)](https://hex.pm/packages/tesla)
[![Hexdocs.pm](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/tesla/)
[![Hex.pm](https://img.shields.io/hexpm/dt/tesla.svg)](https://hex.pm/packages/tesla)
[![Hex.pm](https://img.shields.io/hexpm/dw/tesla.svg)](https://hex.pm/packages/tesla)
[![Coverage](https://coveralls.io/repos/github/elixir-tesla/tesla/badge.svg?branch=master)](https://coveralls.io/github/elixir-tesla/tesla?branch=master)

`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](https://github.com/lostisland/faraday) from Ruby.

## Getting started

Add `:tesla` as dependency in `mix.exs`:

<!-- {x-release-please-start-version} -->
```elixir
defp deps do
  [
    {:tesla, "~> 1.23.0"},
    # optional, required by JSON middleware
    {:jason, "~> 1.4"},
    # optional, required by Mint adapter, recommended
    {:mint, "~> 1.0"}
  ]
end
```
<!-- {x-release-please-end} -->

> #### :httpc as default Adapter {: .error}
> The default adapter is erlang's built-in `httpc`, primarily to avoid
> additional
> dependencies when using `Tesla` 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](https://github.com/elixir-tesla/tesla/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Ahttpc+).
> Instead, consider using `Mint`, `Finch`, or `Hackney` adapters.
> We believe that such security issues should be addressed by `:httpc` itself
> and we are not planning to fix them in `Tesla` due to backward compatibility.

Configure default adapter in `config/config.exs`.

```elixir
# 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://httpbi