View Source
ExCurl
Elixir bindings for libcurl using Zig's C interoperability.
Installation
The package can be installed by adding ex_curl
to your list of dependencies in mix.exs
:
def deps do
[
{:ex_curl, "~> 0.3.0"}
]
end
To install ex_curl
in a Livebook, you can use Mix.install/2
:
Mix.install([
{:ex_curl, "~> 0.3.0"}
])
Usage
ExCurl.get("https://httpbin.org/get")
# => {:ok, %ExCurl.Response{status_code: 200, headers: %{"content-type" => "application/json", body: "{...}"}}}
# view request metrics
ExCurl.get!("https://httpbin.org/get", return_metrics: true)
# => %ExCurl.Response{status_code: 200, metrics: %ExCurl.ResponseMetrics{total_time: 0.2, ...}, ...}}
# submit a form
ExCurl.post("https://httpbin.org/post", body: "text=#{URI.encode_www_form("some value")}")
# => {:ok, %ExCurl.Response{status_code: 200, body: "{...}"}}}
General usage examples and documentation can be found on the ExCurl module documentation page.
HTTP Clients and Shared Defaults
# create clients and set default options
defmodule CustomClient do
use ExCurl.Client, defaults: [headers: %{"User-Agent" => "custom-user-agent"}]
end
# all requests using CustomClient will use the custom User-Agent header
CustomClient.get("https://httpbin.org/get")
# => {:ok, %ExCurl.Response{status_code: 200, body: ".."}}
You can use ExCurl.Client
on any module to create HTTP Clients.
Below is an example of a GitHub API client based on the great Tesla documentation:
defmodule GitHubClient do
use ExCurl.Client, defaults: [base_url: "https://api.github.com"]
def user_repos(username), do: get("/users/#{username}/repos")
end
# we can now call the GitHubClient with the pre-defined HTTP verb functions:
GitHubClient.get("/users/danielrudn/repos")
# => {:ok, %ExCurl.Response{status_code: 200, body: "{....}"}}
# or call our custom defined functions:
GitHubClient.user_repos("danielrudn")
# => {:ok, %ExCurl.Response{status_code: 200, body: "{....}"}}
More examples and details on using ExCurl.Client
are available on the ExCurl.Client module documentation page.
Documentation
Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/ex_curl.
Acknowledgements
This library is built on top of libcurl as a NIF using Zigler and Zig's C interoperability.