HTTP client for Elixir, based on ibrowse. Continues the HTTPun tradition of HTTParty, HTTPretty, HTTParrot and HTTPie.
Add HTTPotion and ibrowse to your project's dependencies in mix.exs
:
defp deps do
[
{:ibrowse, github: "cmullaparthi/ibrowse", tag: "v4.1.2"},
{:httpotion, "~> 2.1.0"}
]
end
def application do
[applications: [:httpotion]]
# Application dependency auto-starts it, otherwise: HTTPotion.start
end
And fetch your project's dependencies:
$ mix deps.get
Some basic examples:
Note: You can load HTTPotion into the Elixir REPL by
executing this command from the root of your project:
$ iex -S mix
iex> response = HTTPotion.get "httpbin.org/get"
%HTTPotion.Response{body: "...", headers: [Connection: "keep-alive", ...], status_code: 200}
iex> HTTPotion.Response.success?(response)
true
iex> response = HTTPotion.post "https://httpbin.org/post", [body: "hello=world", headers: ["User-Agent": "My App"]]
%HTTPotion.Response{body: "...", headers: [Connection: "keep-alive", ...], status_code: 200}
iex> response = HTTPotion.request :propfind, "http://httpbin.org/post", [body: "I have no idea what I'm doing"]
%HTTPotion.Response{body: "...", headers: [Connection: "keep-alive", ...], status_code: 405}
iex> response = HTTPotion.get "httpbin.org/basic-auth/foo/bar", [basic_auth: {"foo", "bar"}]
%HTTPotion.Response{body: "...", headers: ["Access-Control-Allow-Credentials": "true", ...], status_code: 200}
# Passing options to ibrowse (note that it usually takes char_lists, not elixir strings)
# And no, you can't use that proxy :D
iex> response = HTTPotion.get "http://ip6.me", [ ibrowse: [ proxy_host: 'fc81:6134:ba6c:8458:c99f:6c01:6472:8f1e', proxy_port: 8118 ] ]
%HTTPotion.Response{body: "...", headers: [Connection: "keep-alive", ...], status_code: 200}
# The default timeout is 5000 ms, but can be changed
iex> HTTPotion.get "http://example.com", [timeout: 10_000]
iex> HTTPotion.get "http://localhost:1"
** (HTTPotion.HTTPError) econnrefused
The Response
is a struct โ you access its fields like this: response.body
.
HTTPError
is an exception that happens when the request fails.
Note: the API changed in 2.0.0, body and headers are options now!
You can extend HTTPotion.Base
to make cool API clients or something (this example uses jsx for JSON):
defmodule GitHub do
use HTTPotion.Base
def process_url(url) do
"https://api.github.com/" <> url
end
def process_request_headers(headers) do
Dict.put headers, :"User-Agent", "github-potion"
end
def process_response_body(body) do
body |> IO.iodata_to_binary |> :jsx.decode
|> Enum.map fn ({k, v}) -> { String.to_atom(k), v } end
|> :orddict.from_list
end
end
iex> GitHub.get("users/myfreeweb").body[:public_repos]
37
Read the source to see all the hooks. It's not intimidating at all, pretty easy to read actually :-)
Don't forget that IO.iodata_to_binary
is called by default in process_response_body
and process_response_chunk
, you'll probably need to call it too.
Hey, we're on the Erlang VM, right? Every serious OTP app probably makes a lot of these. It's easy to do in HTTPotion.
iex> HTTPotion.get "http://httpbin.org/get", [stream_to: self]
%HTTPotion.AsyncResponse{id: {1372,8757,656584}}
iex> flush
%HTTPotion.AsyncHeaders{id: {1372,8757,656584}, status_code: 200, headers: ["Transfer-Encoding": "chunked", ...]}
%HTTPotion.AsyncChunk{id: {1372,8757,656584}, chunk: "<!DOCTYPE html>\n..."}
%HTTPotion.AsyncEnd{id: {1372,8757,656584}}
Note that instead of process_response_body
, process_response_chunk
is called on the chunks before sending them out to the receiver (the stream_to
process).
ibrowse allows you to use its separate worker processes directly.
We expose this functionality through the direct
option.
Don't forget that you have to pass the URL to the worker process, which means the worker only communicates with one server (domain!)
iex> {:ok, worker_pid} = HTTPotion.spawn_worker_process("http://httpbin.org")
iex> HTTPotion.get "httpbin.org/get", [direct: worker_pid]
%HTTPotion.Response{body: "...", headers: ["Connection": "close", ...], status_code: 200}
You can even combine it with async!
iex> {:ok, worker_pid} = HTTPotion.spawn_worker_process("http://httpbin.org")
iex> HTTPotion.post "httpbin.org/post", [direct: worker_pid, stream_to: self, headers: ["User-Agent": "hello it's me"]]
%HTTPotion.AsyncResponse{id: {1372,8757,656584}}
Please feel free to submit pull requests! Bugfixes and simple non-breaking improvements will be accepted without any questions :-)
By participating in this project you agree to follow the Contributor Code of Conduct.
The list of contributors is available on GitHub.
This is free and unencumbered software released into the public domain.
For more information, please refer to the UNLICENSE
file or unlicense.org.