Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Misc doc changes #446

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 26 additions & 5 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,9 +1,30 @@
/_build
/deps
# The directory Mix will write compiled artifacts to.
/_build/

# If you run "mix test --cover", coverage assets end up here.
/cover/

# The directory Mix downloads your dependencies sources to.
/deps/

# Where third-party dependencies like ExDoc output generated docs.
/doc/

# Ignore .fetch files in case you like to edit your project deps locally.
/.fetch

# If the VM crashes, it generates a dump, let's ignore it too.
erl_crash.dump

# Also ignore archive artifacts (built via "mix archive.build").
*.ez
/doc
/cover

# Ignore package tarball (built via "mix hex.build").
tesla-*.tar

# Temporary files for e.g. tests
/tmp

# Misc
.tool-versions
/sandbox
.elixir_ls
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
The MIT License (MIT)

Copyright (c) 2015-2020 Tymon Tobolski
Copyright (c) 2015-2021 Tymon Tobolski

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
50 changes: 25 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

[![Build Status](https://github.com/teamon/tesla/workflows/Test/badge.svg?branch=master)](https://github.com/teamon/tesla/actions)
[![Hex.pm](https://img.shields.io/hexpm/v/tesla.svg)](http://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)
[![codecov](https://codecov.io/gh/teamon/tesla/branch/master/graph/badge.svg)](https://codecov.io/gh/teamon/tesla)
Expand All @@ -14,6 +15,8 @@ It embraces the concept of middleware when processing the request/response cycle
released version on Hex. See [the documentation](http://hexdocs.pm/tesla) for
the documentation of the version you're using.

For list of changes, checkout the latest [release notes](https://github.com/teamon/tesla/releases).

---

## [`0.x` to `1.0` Migration Guide](https://github.com/teamon/tesla/wiki/0.x-to-1.0-Migration-Guide)
Expand Down Expand Up @@ -59,18 +62,14 @@ See below for documentation.

## Installation

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

```elixir
defp deps do
[
{:tesla, "~> 1.4.0"},

# optional, but recommended adapter
{:hackney, "~> 1.16.0"},

# optional, required by JSON middleware
{:jason, ">= 1.0.0"}
{:hackney, "~> 1.16.0"}, # optional, but recommended adapter
{:jason, ">= 1.0.0"} # optional, required by JSON middleware
]
end

Expand Down Expand Up @@ -113,17 +112,17 @@ This is very similar to how [Plug Router](https://github.com/elixir-plug/plug#th
- [`Tesla.Middleware.Headers`](https://hexdocs.pm/tesla/Tesla.Middleware.Headers.html) - set request headers
- [`Tesla.Middleware.Query`](https://hexdocs.pm/tesla/Tesla.Middleware.Query.html) - set query parameters
- [`Tesla.Middleware.Opts`](https://hexdocs.pm/tesla/Tesla.Middleware.Opts.html) - set request options
- [`Tesla.Middleware.FollowRedirects`](https://hexdocs.pm/tesla/Tesla.Middleware.FollowRedirects.html) - follow 3xx redirects
- [`Tesla.Middleware.MethodOverride`](https://hexdocs.pm/tesla/Tesla.Middleware.MethodOverride.html) - set X-Http-Method-Override
- [`Tesla.Middleware.Logger`](https://hexdocs.pm/tesla/Tesla.Middleware.Logger.html) - log requests (method, url, status, time)
- [`Tesla.Middleware.KeepRequest`](https://hexdocs.pm/tesla/Tesla.Middleware.KeepRequest.html) - keep request body & headers
- [`Tesla.Middleware.FollowRedirects`](https://hexdocs.pm/tesla/Tesla.Middleware.FollowRedirects.html) - follow HTTP 3xx redirects
- [`Tesla.Middleware.MethodOverride`](https://hexdocs.pm/tesla/Tesla.Middleware.MethodOverride.html) - set `X-Http-Method-Override` header
- [`Tesla.Middleware.Logger`](https://hexdocs.pm/tesla/Tesla.Middleware.Logger.html) - log requests (method, url, status, and time)
- [`Tesla.Middleware.KeepRequest`](https://hexdocs.pm/tesla/Tesla.Middleware.KeepRequest.html) - keep request `body` and `headers`
- [`Tesla.Middleware.PathParams`](https://hexdocs.pm/tesla/Tesla.Middleware.PathParams.html) - use templated URLs

### Formats

- [`Tesla.Middleware.FormUrlencoded`](https://hexdocs.pm/tesla/Tesla.Middleware.FormUrlencoded.html) - urlencode POST body, useful for POSTing a map/keyword list
- [`Tesla.Middleware.JSON`](https://hexdocs.pm/tesla/Tesla.Middleware.JSON.html) - JSON request/response body
- [`Tesla.Middleware.Compression`](https://hexdocs.pm/tesla/Tesla.Middleware.Compression.html) - gzip & deflate
- [`Tesla.Middleware.Compression`](https://hexdocs.pm/tesla/Tesla.Middleware.Compression.html) - `gzip` and `deflate`
- [`Tesla.Middleware.DecodeRels`](https://hexdocs.pm/tesla/Tesla.Middleware.DecodeRels.html) - decode `Link` header into `opts[:rels]` field in response

### Auth
Expand All @@ -139,7 +138,7 @@ This is very similar to how [Plug Router](https://github.com/elixir-plug/plug#th

## Runtime middleware

All HTTP functions (`get`, `post`, etc.) can take a dynamic client as the first argument.
All HTTP functions, such as `Tesla.get/3` and `Tesla.post/4`, can take a dynamic client as the first argument.
This allow to use convenient syntax for modifying the behaviour in runtime.

Consider the following case: GitHub API can be accessed using OAuth token authorization.
Expand Down Expand Up @@ -194,13 +193,15 @@ Tesla supports multiple HTTP adapter that do the actual HTTP request processing.
- [`Tesla.Adapter.Mint`](https://hexdocs.pm/tesla/Tesla.Adapter.Mint.html) - [mint](https://github.com/elixir-mint/mint), "Functional HTTP client for Elixir with support for HTTP/1 and HTTP/2"
- [`Tesla.Adapter.Finch`](https://hexdocs.pm/tesla/Tesla.Adapter.Finch.html) - [finch](https://github.com/keathley/finch), "An HTTP client with a focus on performance, built on top of [Mint](https://github.com/elixir-mint/mint) and [NimblePool](https://github.com/dashbitco/nimble_pool)."

When using adapter other than httpc remember to add it to the dependencies list in `mix.exs`
When using adapter other than `:httpc` remember to add it to the dependencies list in `mix.exs`

```elixir
defp deps do
[{:tesla, "~> 1.4.0"},
{:jason, ">= 1.0.0"}, # optional, required by JSON middleware
{:hackney, "~> 1.10"}] # or :gun etc.
[
{:tesla, "~> 1.4.0"},
{:jason, ">= 1.0.0"}, # optional, required by JSON middleware
{:hackney, "~> 1.10"} # when using hackney adapter
]
end
```

Expand Down Expand Up @@ -228,7 +229,7 @@ def new(...) do
end
```

Passing directly to `get`/`post`/etc.
Passing directly to request functions such as `MyClient.get/3` or `Tesla.get/3`.

```elixir
MyClient.get("/", opts: [adapter: [recv_timeout: 30_000]])
Expand All @@ -253,11 +254,11 @@ defmodule ElasticSearch do
end
```

Each piece of stream will be encoded as JSON and sent as a new line (conforming to JSON stream format)
Each piece of stream will be encoded as JSON and sent as a new line (conforming to JSON stream format).

## Multipart

You can pass a `Tesla.Multipart` struct as the body.
You can pass a `Tesla.Multipart` struct as the body:

```elixir
alias Tesla.Multipart
Expand All @@ -278,7 +279,7 @@ mp =

## Testing

You can set the adapter to `Tesla.Mock` in tests.
You can set the adapter to `Tesla.Mock` in tests:

```elixir
# config/test.exs
Expand Down Expand Up @@ -318,8 +319,7 @@ end

## Writing middleware

A Tesla middleware is a module with `c:Tesla.Middleware.call/3` function, that at some point calls `Tesla.run/2` with `env` and `next` to process
the rest of stack.
A Tesla middleware is a module with `c:Tesla.Middleware.call/3` function, that at some point calls `Tesla.run/2` with `env` and `next` to process the rest of stack.

```elixir
defmodule MyMiddleware do
Expand Down Expand Up @@ -382,7 +382,7 @@ defmodule Tesla.Middleware.SomeMiddleware do
Longer description, including e.g. additional dependencies.


### Example usage
### Examples

```
defmodule MyClient do
Expand Down Expand Up @@ -513,7 +513,7 @@ end

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details

Copyright (c) 2015-2020 [Tymon Tobolski](https://teamon.me/about/)
Copyright (c) 2015-2021 [Tymon Tobolski](https://teamon.me/about/)

---

Expand Down
26 changes: 14 additions & 12 deletions lib/tesla.ex
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ end

defmodule Tesla.Middleware do
@moduledoc """
The middleware specification
The middleware specification.

Middleware is an extension of basic `Tesla` functionality. It is a module that must
implement `c:Tesla.Middleware.call/3`.
Expand All @@ -76,7 +76,7 @@ defmodule Tesla.Middleware do

plug Tesla.Middleware.BaseUrl, "https://example.com"

or inside tuple in case of dynamic middleware (`Tesla.client/1`)
or inside tuple in case of dynamic middleware (`Tesla.client/1`):

Tesla.client([{Tesla.Middleware.BaseUrl, "https://example.com"}])

Expand All @@ -86,7 +86,7 @@ defmodule Tesla.Middleware do

See `c:Tesla.Middleware.call/3` for details.

### Example
### Examples

defmodule MyProject.InspectHeadersMiddleware do
@behaviour Tesla.Middleware
Expand Down Expand Up @@ -137,7 +137,7 @@ defmodule Tesla.Adapter do

See `c:Tesla.Adapter.call/2` for details.

### Example
### Examples

defmodule MyProject.CustomAdapter do
alias Tesla.Multipart
Expand Down Expand Up @@ -214,18 +214,20 @@ defmodule Tesla do
@default_adapter Tesla.Adapter.Httpc

@moduledoc """
A HTTP toolkit for building API clients using middlewares
A HTTP toolkit for building API clients using middlewares.

## Building API client

`use Tesla` macro will generate basic http functions (e.g. get, post) inside your module.
`use Tesla` macro will generate basic HTTP functions (e.g. `get/3`, `post/4`,
and etc.) inside your module.

It supports following options:

- `:only` - builder will generate only functions included in the given list
- `:except` - builder will not generate the functions that are listed in the options
- `:docs` - when set to false builder will not add documentation to generated functions

### Example
### Examples

defmodule ExampleApi do
use Tesla, only: [:get], docs: false
Expand Down Expand Up @@ -276,16 +278,16 @@ defmodule Tesla do
end
end

call to `ExampleApi.fetch_data/0` will fail, because request will be missing base url.
call to `ExampleApi.fetch_data/0` will fail, because request will be missing base URL.

## Default adapter

By default `Tesla` is using `Tesla.Adapter.Httpc`, because `:httpc` is included in Erlang/OTP and
doen not require installation of any additional dependency. It can be changed globally with config
does not require installation of any additional dependency. It can be changed globally with config:

config :tesla, :adapter, Tesla.Adapter.Hackney

or by `Tesla.Builder.adapter/2` macro for given API client module
or by `Tesla.Builder.adapter/2` macro for given API client module:

defmodule ExampleApi do
use Tesla
Expand Down Expand Up @@ -379,7 +381,7 @@ defmodule Tesla do

Useful when there's need to store additional middleware data in `Tesla.Env`

## Example
## Examples

iex> %Tesla.Env{opts: []} |> Tesla.put_opt(:option, "value")
%Tesla.Env{opts: [option: "value"]}
Expand Down Expand Up @@ -508,7 +510,7 @@ defmodule Tesla do

Useful when you need to create an URL with dynamic query params from a Keyword list

## Example
## Examples

iex> Tesla.build_url("http://api.example.com", [user: 3, page: 2])
"http://api.example.com?user=3&page=2"
Expand Down
6 changes: 3 additions & 3 deletions lib/tesla/adapter/finch.ex
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ if Code.ensure_loaded?(Finch) do
mix compile
```

## Example usage
## Examples

In order to use Finch, you must start it and provide a `:name`. For example,
in your supervision tree:
Expand Down Expand Up @@ -43,10 +43,10 @@ if Code.ensure_loaded?(Finch) do
## [Finch options](https://hexdocs.pm/finch/Finch.html#request/3)

* `:pool_timeout` - This timeout is applied when a connection is checekd
out from the pool. Default value is `5_000`.
out from the pool. Default value is `5_000`.

* `:receive_timeout` - The maximum time to wait for a response before
returning an error. Default value is `15_000`.
returning an error. Default value is `15_000`.

"""
@behaviour Tesla.Adapter
Expand Down
Loading