ipdata_http (ipdata v1.1.0)

View Source

HTTP transport layer for the ipdata API.

Wraps OTP's httpc module to provide GET and POST requests with proper TLS configuration, JSON parsing, and error handling.

Every request goes through a dedicated httpc profile named ipdata that keeps persistent HTTP/1.1 keep-alive connections to the API, so the TCP and TLS handshake is paid once per connection instead of once per request. The profile is started by ipdata_app when the application starts; if the application was never started, the first request starts it on demand.

Summary

Types

The two httpc request shapes used here: without and with a body.

Functions

Perform an HTTP GET request.

Perform an HTTP POST request with a JSON body.

Options applied to the ipdata httpc profile.

Start the ipdata httpc profile and apply profile_options/0.

Types

headers/0

-type headers() :: [{string(), string()}].

The two httpc request shapes used here: without and with a body.

http_options/0

-type http_options() ::
          [{timeout, pos_integer()} |
           {connect_timeout, pos_integer()} |
           {ssl, [ssl:tls_client_option()]}].

method/0

-type method() :: get | post.

request/0

-type request() :: {string(), headers()} | {string(), headers(), string(), binary()}.

request_options/0

-type request_options() :: [{body_format, binary}].

Functions

get(URL, Headers, Timeout)

-spec get(URL :: string(), Headers :: [{string(), string()}], Timeout :: pos_integer()) ->
             {ok, jsx:json_term()} | {error, term()}.

Perform an HTTP GET request.

Returns the decoded JSON response body on success, or an error tuple on failure.

post(URL, Headers, Body, Timeout)

-spec post(URL :: string(),
           Headers :: [{string(), string()}],
           Body :: jsx:json_term(),
           Timeout :: pos_integer()) ->
              {ok, jsx:json_term()} | {error, term()}.

Perform an HTTP POST request with a JSON body.

The body term is encoded to JSON before sending. Returns the decoded JSON response body on success, or an error tuple on failure.

A POST is not idempotent, so httpc hands a request back with {error, socket_closed_remotely} when the server closed the connection before answering it. That request is retried exactly once; httpc has already discarded the closed connection, so the retry goes out on a fresh one. HTTP error statuses are never retried.

profile_options()

-spec profile_options() -> [{atom(), term()}].

Options applied to the ipdata httpc profile.

The defaults keep up to 16 persistent connections per host, queue at most 4 requests on each of them, and close a connection after 60 seconds idle:

  [{max_sessions, 16}, {max_keep_alive_length, 4}, {keep_alive_timeout, 60000}]

Each entry can be overridden, and further httpc:set_options/2 options added, through the httpc_options key of the ipdata application environment:

  {ipdata, [{httpc_options, [{max_sessions, 4},
                             {https_proxy, {{"proxy.example.com", 3128}, []}}]}]}

start_profile()

-spec start_profile() -> ok | {error, term()}.

Start the ipdata httpc profile and apply profile_options/0.

The profile is started under the inets supervision tree, so inets must be running. An already running profile is accepted and its options are (re)applied, which makes the function safe to call more than once.