restclient is a library to help with consuming RESTful web services. It supports encoding and decoding JSON, Percent and XML and comes with a convenience function for working with urls and query parameters.
REQUIRES OTP 27 OR LATER: JSON is handled by the json module from stdlib,
which was introduced in OTP 27.
IMPORTANT: The library has been updated to use hackney v4, but the usage
is backwards compatible with v1. In case an older version is required, it must
be explicitly overriden by the top level application.
Include restclient as a rebar dependency with:
{deps, [{restc, {git, "https://github.com/kivra/restclient.git", {tag, "0.12.0"}}}]}.
The releases on hex.pm are no longer maintained, so depend on a git tag.
Start the application (which brings up hackney and, with it, ssl), then use
the client as:
1> application:ensure_all_started(restc).
{ok, [...]}
2> restc:request(get, "https://api.github.com").
{ok,200,
[{<<"Server">>,<<"GitHub.com">>},
{<<"Date">>,<<"Thu, 11 May 2017 07:36:16 GMT">>},
{<<"Content-Type">>,<<"application/json; charset=utf-8">>},
{<<"Content-Length">>,<<"2039">>},
{<<"Status">>,<<"200 OK">>},
{<<"X-GitHub-Req"...>>,<<"8E05:5C9"...>>}],
[{<<"current_user_url">>,<<"https://api.github.com/user">>},
{<<"current_user_authorizations_html_url">>,
<<"https://github.com/settings/connections/applications{/client_id}">>},
{<<"authorizations_url">>,
<<"https://api.github.com/authorizations">>},
{<<...>>,...},
{...}|...]}
3> restc:request(get, "https://api.github.com/herp-derp-404", [200]).
{error,404,
[{<<"Server">>,<<"GitHub.com">>},
{<<"Date">>,<<"Thu, 11 May 2017 07:37:27 GMT">>},
{<<"Content-Type">>,<<"application/json; charset=utf-8">>},
{<<"Content-Length">>,<<"77">>},
{<<"Status">>,<<"404 Not Found">>},
{<<"X-RateLimit-Limit">>,<<"60">>},
{<<"X-RateLimit-Remaining">>,<<"56">>},
{<<"X-RateLimit-Reset">>,<<"1494491776">>},
{<<"X-GitHub-Media-Type">>,<<"github.v3">>},
{<<"Access-Control-Expose-Headers">>,
<<"ETag, Link, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit"...>>},
{<<"Access-Control-Allow-Origin">>,<<"*">>},
{<<"Content-Security-Policy">>,<<"default-src 'none'">>},
{<<"Strict-Transport-Security">>,
<<"max-age=31536000; includeSubdomains; preload">>},
{<<"X-Content-Type-Options">>,<<"nosniff">>},
{<<"X-Frame-Options">>,<<"deny">>},
{<<"X-XSS-Protection">>,<<"1; mode=block">>},
{<<"X-GitHub-Request-Id">>,
<<"8C1D:5C90:54F34B8:6C6FF4D:59"...>>}],
[{<<"message">>,<<"Not Found">>},
{<<"documentation_url">>,
<<"https://developer.github.com/v3">>}]}
There's also convenience functions for working with urls and query string:
7> restc:construct_url("http://www.example.com/te", "res/res1/res2", [{"q1", "qval1"}, {"q2", "qval2"}]).
"http://www.example.com/te/res/res1/res2?q1=qval1&q2=qval2"The KIVRA restclient library uses an MIT license. So go ahead and do what you want!
Lots of fun!