tesla

v1.0.0-beta.1

tesla v1.0.0-beta.1 Tesla View Source

A HTTP toolkit for building API clients using middlewares

Include Tesla module in your api client:

defmodule ExampleApi do
  use Tesla

  plug Tesla.Middleware.BaseUrl, "http://api.example.com"
  plug Tesla.Middleware.JSON
end

Link to this section Summary

Types

option()

Functions

build_adapter(fun)
build_client(pre, post \\ [])

Dynamically build client from list of middlewares

build_url(url, query)
delete(client, url, opts)

Perform a DELETE request

delete!(client, url, opts)

Perform a DELETE request

delete_header(env, key)
get(client, url, opts)

Perform a GET request

get!(client, url, opts)

Perform a GET request

get_header(env, key)
get_headers(env, key)
head(client, url, opts)

Perform a HEAD request

head!(client, url, opts)

Perform a HEAD request

options(client, url, opts)

Perform a OPTIONS request

options!(client, url, opts)

Perform a OPTIONS request

patch(client, url, body, opts)

Perform a PATCH request

patch!(client, url, body, opts)

Perform a PATCH request

post(client, url, body, opts)

Perform a POST request

post!(client, url, body, opts)

Perform a POST request

put(client, url, body, opts)

Perform a PUT request

put!(client, url, body, opts)

Perform a PUT request

put_body(env, body)
put_header(env, key, value)
put_headers(env, list)
put_opt(env, key, value)
request(client \\ %Tesla.Client{}, options)

Perform a request

request!(client \\ %Tesla.Client{}, options)

Perform request and raise in case of error

run(env, list)
run_default_adapter(env, opts \\ [])
trace(client, url, opts)

Perform a TRACE request

trace!(client, url, opts)

Perform a TRACE request

Link to this section Types

Link to this type option() View Source 
option() ::
  {:method, Tesla.Env.method()}
  | {:url, Tesla.Env.url()}
  | {:query, Tesla.Env.query()}
  | {:headers, Tesla.Env.headers()}
  | {:body, Tesla.Env.body()}
  | {:opts, Tesla.Env.opts()}

Link to this section Functions

Link to this function build_client(pre, post \\ []) View Source

Dynamically build client from list of middlewares.

defmodule ExampleAPI do
  use Tesla

  def new(token) do
    Tesla.build_client([
      {Tesla.Middleware.Headers, [{"authorization", token}]
    ])
  end
end

client = ExampleAPI.new(token: "abc")
client |> ExampleAPI.get("/me")
Link to this function delete(client, url, opts) View Source 
delete(Tesla.Env.client(), Tesla.Env.url(), [option()]) :: Tesla.Env.result()

Perform a DELETE request.

See request/1 or request/2 for options definition.

delete("/users")
delete("/users", query: [scope: "admin"])
delete(client, "/users")
delete(client, "/users", query: [scope: "admin"])
Link to this function delete!(client, url, opts) View Source 
delete!(Tesla.Env.client(), Tesla.Env.url(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a DELETE request.

See request!/1 or request!/2 for options definition.

delete!("/users")
delete!("/users", query: [scope: "admin"])
delete!(client, "/users")
delete!(client, "/users", query: [scope: "admin"])
Link to this function delete_header(env, key) View Source 
delete_header(Tesla.Env.t(), binary()) :: Tesla.Env.t()
Link to this function get(client, url, opts) View Source 
get(Tesla.Env.client(), Tesla.Env.url(), [option()]) :: Tesla.Env.result()

Perform a GET request.

See request/1 or request/2 for options definition.

get("/users")
get("/users", query: [scope: "admin"])
get(client, "/users")
get(client, "/users", query: [scope: "admin"])
Link to this function get!(client, url, opts) View Source 
get!(Tesla.Env.client(), Tesla.Env.url(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a GET request.

See request!/1 or request!/2 for options definition.

get!("/users")
get!("/users", query: [scope: "admin"])
get!(client, "/users")
get!(client, "/users", query: [scope: "admin"])
Link to this function get_header(env, key) View Source 
get_header(Tesla.Env.t(), binary()) :: binary() | nil
Link to this function get_headers(env, key) View Source 
get_headers(Tesla.Env.t(), binary()) :: [binary()]
Link to this function head(client, url, opts) View Source 
head(Tesla.Env.client(), Tesla.Env.url(), [option()]) :: Tesla.Env.result()

Perform a HEAD request.

See request/1 or request/2 for options definition.

head("/users")
head("/users", query: [scope: "admin"])
head(client, "/users")
head(client, "/users", query: [scope: "admin"])
Link to this function head!(client, url, opts) View Source 
head!(Tesla.Env.client(), Tesla.Env.url(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a HEAD request.

See request!/1 or request!/2 for options definition.

head!("/users")
head!("/users", query: [scope: "admin"])
head!(client, "/users")
head!(client, "/users", query: [scope: "admin"])
Link to this function options(client, url, opts) View Source 
options(Tesla.Env.client(), Tesla.Env.url(), [option()]) :: Tesla.Env.result()

Perform a OPTIONS request.

See request/1 or request/2 for options definition.

options("/users")
options("/users", query: [scope: "admin"])
options(client, "/users")
options(client, "/users", query: [scope: "admin"])
Link to this function options!(client, url, opts) View Source 
options!(Tesla.Env.client(), Tesla.Env.url(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a OPTIONS request.

See request!/1 or request!/2 for options definition.

options!("/users")
options!("/users", query: [scope: "admin"])
options!(client, "/users")
options!(client, "/users", query: [scope: "admin"])
Link to this function patch(client, url, body, opts) View Source 
patch(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.result()

Perform a PATCH request.

See request/1 or request/2 for options definition.

patch("/users", %{name: "Jon"})
patch("/users", %{name: "Jon"}, query: [scope: "admin"])
patch(client, "/users", %{name: "Jon"})
patch(client, "/users", %{name: "Jon"}, query: [scope: "admin"])
Link to this function patch!(client, url, body, opts) View Source 
patch!(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a PATCH request.

See request!/1 or request!/2 for options definition.

patch!("/users", %{name: "Jon"})
patch!("/users", %{name: "Jon"}, query: [scope: "admin"])
patch!(client, "/users", %{name: "Jon"})
patch!(client, "/users", %{name: "Jon"}, query: [scope: "admin"])
Link to this function post(client, url, body, opts) View Source 
post(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.result()

Perform a POST request.

See request/1 or request/2 for options definition.

post("/users", %{name: "Jon"})
post("/users", %{name: "Jon"}, query: [scope: "admin"])
post(client, "/users", %{name: "Jon"})
post(client, "/users", %{name: "Jon"}, query: [scope: "admin"])
Link to this function post!(client, url, body, opts) View Source 
post!(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a POST request.

See request!/1 or request!/2 for options definition.

post!("/users", %{name: "Jon"})
post!("/users", %{name: "Jon"}, query: [scope: "admin"])
post!(client, "/users", %{name: "Jon"})
post!(client, "/users", %{name: "Jon"}, query: [scope: "admin"])
Link to this function put(client, url, body, opts) View Source 
put(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.result()

Perform a PUT request.

See request/1 or request/2 for options definition.

put("/users", %{name: "Jon"})
put("/users", %{name: "Jon"}, query: [scope: "admin"])
put(client, "/users", %{name: "Jon"})
put(client, "/users", %{name: "Jon"}, query: [scope: "admin"])
Link to this function put!(client, url, body, opts) View Source 
put!(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a PUT request.

See request!/1 or request!/2 for options definition.

put!("/users", %{name: "Jon"})
put!("/users", %{name: "Jon"}, query: [scope: "admin"])
put!(client, "/users", %{name: "Jon"})
put!(client, "/users", %{name: "Jon"}, query: [scope: "admin"])
Link to this function put_header(env, key, value) View Source 
put_header(Tesla.Env.t(), binary(), binary()) :: Tesla.Env.t()
Link to this function put_headers(env, list) View Source 
put_headers(Tesla.Env.t(), [{binary(), binary()}]) :: Tesla.Env.t()
Link to this function put_opt(env, key, value) View Source
Link to this function request(client \\ %Tesla.Client{}, options) View Source 
request(Tesla.Env.client(), [option()]) :: Tesla.Env.result()

Perform a request

Options:

  • :method - the request method, one of [:head, :get, :delete, :trace, :options, :post, :put, :patch]
  • :url - either full url e.g. “http://example.com/some/path” or just “/some/path” if using Tesla.Middleware.BaseUrl
  • :query - a keyword list of query params, e.g. [page: 1, per_page: 100]
  • :headers - a keyworld list of headers, e.g. [{"content-type", "text/plain"}]

  • :body - depends on used middleware:

    • by default it can be a binary
    • if using e.g. JSON encoding middleware it can be a nested map
    • if adapter supports it it can be a Stream with any of the above
  • :opts - custom, per-request middleware or adapter options

Examples:

ExampleApi.request(method: :get, url: "/users/path")

You can also use shortcut methods like:

ExampleApi.get("/users/1")

or

ExampleApi.post(client, "/users", %{name: "Jon"})
Link to this function request!(client \\ %Tesla.Client{}, options) View Source 
request!(Tesla.Env.client(), [option()]) :: Tesla.Env.t() | no_return()

Perform request and raise in case of error.

This is similar to request/2 behaviour from Tesla 0.x

See request/2 for list of available options.

Link to this function run_default_adapter(env, opts \\ []) View Source
Link to this function trace(client, url, opts) View Source 
trace(Tesla.Env.client(), Tesla.Env.url(), [option()]) :: Tesla.Env.result()

Perform a TRACE request.

See request/1 or request/2 for options definition.

trace("/users")
trace("/users", query: [scope: "admin"])
trace(client, "/users")
trace(client, "/users", query: [scope: "admin"])
Link to this function trace!(client, url, opts) View Source 
trace!(Tesla.Env.client(), Tesla.Env.url(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a TRACE request.

See request!/1 or request!/2 for options definition.

trace!("/users")
trace!("/users", query: [scope: "admin"])
trace!(client, "/users")
trace!(client, "/users", query: [scope: "admin"])