1.2 draft

[teamon]

Tesla 1.2 Draft

This is an early draft of proposed changes for next version of tesla.
All feedback is more than welcome - the more I know how you all use this library the better it can become 💃

There are three main points I'd like to tackle (A, B and C). This does not mean any other issues/improvements won't make it into the next release, these are the biggest & hardest ones.

A. Promote macro-less clients

Instead of

defmodule Github do
  use Tesla

  plug Tesla.Middleware.BaseUrl, "https://api.github.com"
  plug Tesla.Middleware.JSON

  adapter Tesla.Adapter.Hackney

  def repos, do: get("/repos")
end

use this one

defmodule Github do
  @middleware [
    {Tesla.Middleware.BaseUrl, "https://api.github.com"},
    Tesla.Middleware.JSON
  ]

  @adapter Tesla.Adapter.Hackney

  def repos, do: Tesla.get(client(), "/repos")

  defp client, do: Tesla.client(@middleware, @adapter)
end

or with dynamic middleware/adapter

defmodule MyApi do
  @default_middleware [
    {Tesla.Middleware.BaseUrl, "https://api.github.com"},
    Tesla.Middleware.JSON
  ]

  def items(client \\ new()), do: Tesla.get(client, "/items")

  def new(user_token, opts \\ []) do
    middleware = [{Tesla.Middleware.Headers, [{"authorization", "Bearer #{user_token}"}]}]
    Tesla.client(middleware ++ @default_middleware, opts[:adapter] || @adapter)
  end
end

The reasons for such change are (unordered):

• Do not worry about polluting your module with public get/post/... functions
• No more name collision (I'm looking at you delete function)
• It becomes clear what happens with middleware arguments (Builder blurries the lines between module and functions #220)
• There is no difference in readability compared to the macro-based version
• It allows greater flexibility to decide on middleware/adapter at runtime (Allow the adapter to be configured explicitly at runtime #219).

The changes required are very minimal:

• Introduce Tesla.client/1 and Tesla.client/2 (Should it be called Tesla.new?)
• Update adapter README with configuration examples
• Update README and examples (while keeping the DSL docs!)

---

WDYT?

[amatalai]

Introduce Tesla.client/1 and Tesla.client/2 (Should it be called Tesla.new?)

I vote for client. Tesla.new would be a good name if it was supposed to create %Tesla{} struct

Update README and examples (while keeping the DSL docs!)

Do we have a plan to deprecate/remove macros in the long run? Maybe something like:

• 1.2 soft deprecation (explained in @doc)
• 1.3 hard deprecation (@doc deprecated: "use ... instead)
• 2.0 removed

[timeout] if the library does not implement it it will have to be implemented on the adapter level (most probably in a similar fashion as current timeout middleware).

Wouldn't it cause same issues as current timeout middleware?

[teamon]

Do we have a plan to deprecate/remove macros in the long run?

I think we can keep both, I don't have a strong urge to remove macros.

Wouldn't it cause same issues as current timeout middleware?

No, since in test you'd replace that adapter with Tesla.Mock (or other)

[teamon]

Regarding a well-defined adapter interface:

httpc return type:

{ok, Result} | {ok, saved_to_file} | {error, term()}

hackney return type:

{ok, integer(), list(), client_ref()} | {ok, integer(), list()} | {error, term()}

ibrowse return type:

{ok, Status, ResponseHeaders, ResponseBody} | {ibrowse_req_id, req_id()} | {error, term()}

Since none of the current adapters define proper error contract, I don't see how could tesla enforce one.