@spec add_params_to_url(binary(), list()) :: binary()

Take an existing URI and add addition params, appending and replacing as necessary.

Examples

iex> add_params_to_url("http://example.com/wat", [])
"http://example.com/wat"

iex> add_params_to_url("http://example.com/wat", [q: 1])
"http://example.com/wat?q=1"

iex> add_params_to_url("http://example.com/wat", [q: 1, t: 2])
"http://example.com/wat?q=1&t=2"

iex> add_params_to_url("http://example.com/wat", %{q: 1, t: 2})
"http://example.com/wat?q=1&t=2"

iex> add_params_to_url("http://example.com/wat?q=1&t=2", [])
"http://example.com/wat?q=1&t=2"

iex> add_params_to_url("http://example.com/wat?q=1", [t: 2])
"http://example.com/wat?q=1&t=2"

iex> add_params_to_url("http://example.com/wat?q=1", [q: 3, t: 2])
"http://example.com/wat?q=3&t=2"

iex> add_params_to_url("http://example.com/wat?q=1&s=4", [q: 3, t: 2])
"http://example.com/wat?q=3&s=4&t=2"

iex> add_params_to_url("http://example.com/wat?q=1&s=4", %{q: 3, t: 2})
"http://example.com/wat?q=3&s=4&t=2"

Same as authorization_header/2 but defaults initial headers to include @user_agent.

@spec authorization_header(Tentacat.Client.auth(), list()) :: list()

There are two ways to authenticate through GitHub API v3:

• Basic authentication
• OAuth2 Token
• JWT

This function accepts both.

Examples

iex> Tentacat.authorization_header(%{user: "user", password: "password"}, [])
[{"Authorization", "Basic dXNlcjpwYXNzd29yZA=="}]

iex> Tentacat.authorization_header(%{access_token: "92873971893"}, [])
[{"Authorization", "token 92873971893"}]

iex> Tentacat.authorization_header(%{jwt: "92873971893"}, [])
[{"Authorization", "Bearer 92873971893"}]

More info at: http://developer.github.com/v3/#authentication

@spec delete(binary(), headers(), Keyword.t()) ::
  {:ok,
   HTTPoison.Response.t()
   | HTTPoison.AsyncResponse.t()
   | HTTPoison.MaybeRedirect.t()}
  | {:error, HTTPoison.Error.t()}

@spec delete(binary(), Tentacat.Client.t(), any()) :: response()

Issues a DELETE request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

@spec delete!(binary(), headers(), Keyword.t()) ::
  HTTPoison.Response.t()
  | HTTPoison.AsyncResponse.t()
  | HTTPoison.MaybeRedirect.t()

Issues a DELETE request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

@spec get(binary(), headers(), Keyword.t()) ::
  {:ok, HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()}
  | {:error, HTTPoison.Error.t()}

@spec get(binary(), Tentacat.Client.t(), keyword()) :: response()

Issues a GET request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

@spec get(binary(), Tentacat.Client.t(), keyword(), keyword()) ::
  response() | Enumerable.t() | pagination_response()

Underlying utility retrieval function. The options passed affect both the return value and, ultimately, the number of requests made to GitHub.

Options

• :pagination - Can be :none, :manual, :stream, or :auto. Defaults to :auto.

  • :none will only return the first page. You won't have access to the headers to manually paginate.

  • :auto will block until all the pages have been retrieved and concatenated together. Most of the time, this is what you want. For example, Tentacat.Repositories.list_users("chrismccord") and Tentacat.Repositories.list_users("octocat") have the same interface though one call will page many times and the other not at all.

  • :stream will return a Stream, prepopulated with the first page.

  • :manual will return a 3 element tuple of {page_body, url_for_next_page, auth_credentials}, which will allow you to control the paging yourself.

@spec get!(binary(), headers(), Keyword.t()) ::
  HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()

Issues a GET request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

@spec head(binary(), headers(), Keyword.t()) ::
  {:ok, HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()}
  | {:error, HTTPoison.Error.t()}

Issues a HEAD request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

@spec head!(binary(), headers(), Keyword.t()) ::
  HTTPoison.Response.t() | HTTPoison.AsyncResponse.t()

Issues a HEAD request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

@spec options(binary(), headers(), Keyword.t()) ::
  {:ok,
   HTTPoison.Response.t()
   | HTTPoison.AsyncResponse.t()
   | HTTPoison.MaybeRedirect.t()}
  | {:error, HTTPoison.Error.t()}

Issues an OPTIONS request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

@spec options!(binary(), headers(), Keyword.t()) ::
  HTTPoison.Response.t()
  | HTTPoison.AsyncResponse.t()
  | HTTPoison.MaybeRedirect.t()

Issues a OPTIONS request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

@spec patch(binary(), Tentacat.Client.t(), any()) :: response()

Callback implementation for HTTPoison.Base.patch/3.

@spec patch(binary(), any(), headers(), Keyword.t()) ::
  {:ok,
   HTTPoison.Response.t()
   | HTTPoison.AsyncResponse.t()
   | HTTPoison.MaybeRedirect.t()}
  | {:error, HTTPoison.Error.t()}

Issues a PATCH request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

@spec patch!(binary(), any(), headers(), Keyword.t()) ::
  HTTPoison.Response.t()
  | HTTPoison.AsyncResponse.t()
  | HTTPoison.MaybeRedirect.t()

Issues a PATCH request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

@spec post(binary(), Tentacat.Client.t(), any()) :: response()

Callback implementation for HTTPoison.Base.post/3.

@spec post(binary(), any(), headers(), Keyword.t()) ::
  {:ok,
   HTTPoison.Response.t()
   | HTTPoison.AsyncResponse.t()
   | HTTPoison.MaybeRedirect.t()}
  | {:error, HTTPoison.Error.t()}

Issues a POST request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

@spec post!(binary(), any(), headers(), Keyword.t()) ::
  HTTPoison.Response.t()
  | HTTPoison.AsyncResponse.t()
  | HTTPoison.MaybeRedirect.t()

Issues a POST request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

@spec process_headers(list()) :: any()

Callback implementation for HTTPoison.Base.process_headers/1.

@spec process_request_body(body()) :: body()

Callback implementation for HTTPoison.Base.process_request_body/1.

@spec process_request_headers(headers()) :: headers()

Callback implementation for HTTPoison.Base.process_request_headers/1.

@spec process_request_options(options()) :: options()

Callback implementation for HTTPoison.Base.process_request_options/1.

@spec process_request_params(params()) :: params()

Callback implementation for HTTPoison.Base.process_request_params/1.

@spec process_request_url(url()) :: url()

Callback implementation for HTTPoison.Base.process_request_url/1.

@spec process_response(HTTPoison.Base.response()) :: any()

@spec process_response(
  HTTPoison.Response.t()
  | {integer(), any(), HTTPoison.Response.t()}
) ::
  response()

Callback implementation for HTTPoison.Base.process_response/1.

@spec process_response_body(binary()) :: any()

@spec process_response_body(binary()) :: term()

Callback implementation for HTTPoison.Base.process_response_body/1.

@spec process_response_chunk(binary()) :: any()

Callback implementation for HTTPoison.Base.process_response_chunk/1.

@spec process_response_headers(list()) :: any()

Callback implementation for HTTPoison.Base.process_response_headers/1.

@spec process_response_status_code(integer()) :: any()

Callback implementation for HTTPoison.Base.process_response_status_code/1.

@spec process_status_code(integer()) :: any()

Callback implementation for HTTPoison.Base.process_status_code/1.

@spec process_url(url()) :: url()

Callback implementation for HTTPoison.Base.process_url/1.

@spec put(binary(), Tentacat.Client.t(), any()) :: response()

Callback implementation for HTTPoison.Base.put/3.

@spec put(binary(), any(), headers(), Keyword.t()) ::
  {:ok,
   HTTPoison.Response.t()
   | HTTPoison.AsyncResponse.t()
   | HTTPoison.MaybeRedirect.t()}
  | {:error, HTTPoison.Error.t()}

Issues a PUT request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

@spec put!(binary(), any(), headers(), Keyword.t()) ::
  HTTPoison.Response.t()
  | HTTPoison.AsyncResponse.t()
  | HTTPoison.MaybeRedirect.t()

Issues a PUT request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

@spec request(HTTPoison.Request.t()) ::
  {:ok,
   HTTPoison.Response.t()
   | HTTPoison.AsyncResponse.t()
   | HTTPoison.MaybeRedirect.t()}
  | {:error, HTTPoison.Error.t()}

Issues an HTTP request using an HTTPoison.Request struct.

This function returns {:ok, response}, {:ok, async_response}, or {:ok, maybe_redirect} if the request is successful, {:error, reason} otherwise.

Redirect handling

If the option :follow_redirect is given, HTTP redirects are automatically follow if the method is set to :get or :head and the response's status_code is 301, 302 or 307.

If the method is set to :post, then the only status_code that get's automatically followed is 303.

If any other method or status_code is returned, then this function returns a returns a {:ok, %HTTPoison.MaybeRedirect{}} containing the redirect_url for you to re-request with the method set to :get.

Examples

request = %HTTPoison.Request{
  method: :post,
  url: "https://my.website.com",
  body: "{\"foo\": 3}",
  headers: [{"Accept", "application/json"}]
}

request(request)

@spec request(method(), binary(), any(), headers(), Keyword.t()) ::
  {:ok,
   HTTPoison.Response.t()
   | HTTPoison.AsyncResponse.t()
   | HTTPoison.MaybeRedirect.t()}
  | {:error, HTTPoison.Error.t()}

Issues an HTTP request with the given method to the given url.

This function is usually used indirectly by get/3, post/4, put/4, etc

Args:

• method - HTTP method as an atom (:get, :head, :post, :put, :delete, etc.)
• url - target url as a binary string or char list
• body - request body. See more below
• headers - HTTP headers as an orddict (e.g., [{"Accept", "application/json"}])
• options - Keyword list of options

Body: see type HTTPoison.Request

Options: see type HTTPoison.Request

This function returns {:ok, response}, {:ok, async_response}, or {:ok, maybe_redirect} if the request is successful, {:error, reason} otherwise.

Redirect handling

If the option :follow_redirect is given, HTTP redirects are automatically follow if the method is set to :get or :head and the response's status_code is 301, 302 or 307.

If the method is set to :post, then the only status_code that get's automatically followed is 303.

If any other method or status_code is returned, then this function returns a returns a {:ok, %HTTPoison.MaybeRedirect{}} containing the redirect_url for you to re-request with the method set to :get.

Examples

request(:post, "https://my.website.com", "{\"foo\": 3}", [{"Accept", "application/json"}])

@spec request!(HTTPoison.Request.t()) ::
  HTTPoison.Response.t()
  | HTTPoison.AsyncResponse.t()
  | HTTPoison.MaybeRedirect.t()

Issues an HTTP request an HTTPoison.Request struct. exception in case of failure.

request!/1 works exactly like request/1 but it returns just the response in case of a successful request, raising an exception in case the request fails.

@spec request!(method(), binary(), any(), headers(), Keyword.t()) ::
  HTTPoison.Response.t()
  | HTTPoison.AsyncResponse.t()
  | HTTPoison.MaybeRedirect.t()

Issues an HTTP request with the given method to the given url, raising an exception in case of failure.

request!/5 works exactly like request/5 but it returns just the response in case of a successful request, raising an exception in case the request fails.

Starts HTTPoison and its dependencies.

@spec stream_next(HTTPoison.AsyncResponse.t()) ::
  {:ok, HTTPoison.AsyncResponse.t()} | {:error, HTTPoison.Error.t()}

Requests the next message to be streamed for a given HTTPoison.AsyncResponse.

See request!/5 for more detailed information.