Tesla HTTP Client

Tesla does not parse OpenAPI documents directly. Instead, it provides specific API modules and middleware that you can use when building or hand-writing clients to implement OpenAPI parameter serialization. The in field in OpenAPI determines which Tesla API to use.

Note: path and query parameters use middleware for transformation, while header and cookie collections produce raw header tuples before entering the middleware stack.

For in: "query" parameters, create a module that stores Tesla.OpenAPI.QueryParams metadata. Use Tesla.OpenAPI.QueryParam to define styles. Supported styles include:

• :form
• :space_delimited
• :pipe_delimited
• :deep_object

Crucial: Your Tesla client must include Tesla.Middleware.Query configured with mode: :modern to process the metadata passed via Tesla.Env.private/0.

defmodule MyApi.Operation.GetItem.Query do
  alias Tesla.OpenAPI.{QueryParam, QueryParams}

  defstruct color: nil, filter: nil, "$additional": %{}

  @query_params QueryParams.new!([
                  QueryParam.new!("color", style: :pipe_delimited),
                  QueryParam.new!("filter", style: :deep_object)
                ])

  def query_params, do: @query_params

  def to_query(nil), do: %{}

  def to_query(%__MODULE__{} = query) do
    additional = query."$additional" || %{}

    Map.merge(additional, %{
      "color" => query.color,
      "filter" => query.filter
    })
  end
end

To migrate away from the legacy v1 macro syntax (which uses use Tesla), you must transition to a functional approach where you explicitly manage a Tesla.Client struct. This involves removing the use Tesla macro and replacing plug, adapter, and HTTP method macros with explicit functions and passing a client instance to Tesla functions.

Migration Steps:

1. Remove use Tesla: Delete the use Tesla line from your modules.
2. Convert plug to middleware/0: Instead of using the plug macro, create a function (e.g., middleware/0) that returns a list of middleware modules.
3. Convert adapter to adapter/0: Instead of using the adapter macro, create a function (e.g., adapter/0) that returns the desired adapter module or configuration.
4. Implement a client/0 function: Create a function that returns a Tesla.Client struct by calling Tesla.client(middleware(), adapter()).
5. Update HTTP calls: Replace direct macro calls like get/2 or post/2 with Tesla.get!(client, path), Tesla.post!(client, path, body), etc., passing your new client as the first argument.

# The new pattern for a Tesla client module
defmodule MyApp.MyTeslaClient do
  def client do
    Tesla.client(middleware(), adapter())
  end

  defp middleware do
    [Tesla.Middleware.KeepRequest, Tesla.Middleware.PathParams, Tesla.Middleware.JSON]
  end

  defp adapter do
    # Returning nil uses the default global Tesla adapter
    :my_app
    |> Application.get_env(__MODULE__, [])
    |> Keyword.get(:adapter)
  end

  def do_something do
    # Use the client explicitly in API calls
    Tesla.get!(client(), "/endpoint")
  end
end

In OpenAPI, in: "querystring" treats the entire query string as a single value. This is distinct from standard query parameters and must not be mixed with them.

To implement this, use Tesla.OpenAPI.QueryString.

• Use Tesla.OpenAPI.QueryString.form!(value) to format a value into a query string.
• Use Tesla.OpenAPI.QueryString.raw!(value) if the OpenAPI media type has already produced the exact query string.

Warning: Do not send Tesla.OpenAPI.QueryString through Tesla.Middleware.Query as a normal query map in :modern mode; that middleware expects values backed by Tesla.OpenAPI.QueryParams.

defmodule MyApi.Operation.Search do
  alias MyApi.Client
  alias Tesla.OpenAPI.QueryString

  defstruct query_string: nil

  def handle_operation(%Client{} = client, %__MODULE__{} = operation, opts) do
    request_opts = [
      method: :get,
      url: "/search",
      query: QueryString.form!(operation.query_string),
      opts: opts
    ]

    Tesla.request(client.client, request_opts)
  end
end

The Multi-Client pattern involves passing the client instance as a parameter to your service functions. This allows you to create multiple clients with different configurations (e.g., different base URLs, tokens, or adapters) using the same service logic.

Best for: Multi-tenant applications, interacting with multiple services, or library authors (to ensure flexibility for users).

defmodule MyApp.ServiceName do
  def operation_name(client, body) do
    url = "/endpoint"
    # The client is passed as a parameter
    Tesla.post!(client, url, body)
  end

  def client(opts) do
    middleware = [
      {Tesla.Middleware.BaseUrl, opts[:base_url]},
      {Tesla.Middleware.BearerAuth, token: opts[:bearer_token]}
    ]
    Tesla.client(middleware, opts[:adapter])
  end
end

# Usage:
client = MyApp.ServiceName.client(
  base_url: "https://api.service.com",
  bearer_token: "token_value",
  adapter: Tesla.Adapter.Hackney
)
{:ok, response} = MyApp.ServiceName.operation_name(client, %{key: "value"})