/ 
HTTP-API-Client-0.02 UNAUTHORIZED RELEASE
/ HTTP::API::Client

NAME

HTTP::API::Client - Small foundation for JSON HTTP API clients

SYNOPSIS

use HTTP::API::Client;

my $api = HTTP::API::Client->new(
    base_url => 'https://api.example.com',
    headers  => { Authorization => "Bearer $token" },
    timeout  => 10,
    retry    => {
        attempts   => 3,
        base_delay => 0.25,
        max_delay  => 5,
        jitter     => 1,
    },
);

my $response = $api->get('/users');
my $users = $response->json;

DESCRIPTION

HTTP::API::Client is a deliberately small base layer for building HTTP API clients. It provides base URL handling, default headers, JSON request/response helpers, timeout configuration, structured errors, and conservative retries.

Retry is enabled by default for GET, HEAD, PUT, DELETE, and OPTIONS. POST and PATCH are not retried automatically. Retryable failures include transport errors, HTTP 408, 425, 429, and 5xx responses.

METHODS

new

my $api = HTTP::API::Client->new(
    base_url => 'https://api.example.com',
    headers  => { ... },
    timeout  => 10,
    retry    => { attempts => 3 },
);

base_url is required. headers, timeout, and retry are optional. Retry defaults to three attempts with exponential backoff and jitter.

get, post, put, patch, delete

Convenience methods around request.

request

my $response = $api->request('POST', '/items', json => { ... });

Pass json to encode a Perl value as JSON, or content to send raw content. Per-request headers override default headers. Pass retry => 0 to disable retry for one request, or a retry hash to override the policy.

Non-2xx responses throw HTTP::API::Client::Error after retry is exhausted.

RETRY POLICY

The retry hash accepts attempts, base_delay, max_delay, jitter, and methods. Exponential backoff is capped by max_delay. A numeric Retry-After response header takes precedence over the calculated delay.

ERROR HANDLING

Errors expose stable fields such as category, status, method, url, retryable, retry_after, and request_id. Exact error message wording is not intended as a machine-readable API.

LICENSE

This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.