HTTP::API::Client

A small, dependency-light foundation for building JSON HTTP API clients in Perl.

The goal is not to replace HTTP::Tiny, LWP, or Mojo::UserAgent. It adds the API-client layer that applications repeatedly rebuild: base URLs, JSON request/response handling, default headers, timeout configuration, and structured errors.

Example

use HTTP::API::Client;

my $api = HTTP::API::Client->new(
    base_url => 'https://api.example.com',
    headers  => {
        Authorization => "Bearer $ENV{API_TOKEN}",
    },
    timeout => 10,
);

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

my $created = $api->post(
    '/users',
    json => { name => 'Alice' },
);

Structured errors

eval {
    my $response = $api->get('/users/123');
};

if (my $err = $@) {
    if (ref($err) && $err->isa('HTTP::API::Client::Error')) {
        warn $err->category;    # transport / http / encode / decode
        warn $err->status;      # e.g. 429
        warn $err->retryable;
        warn $err->retry_after;
        warn $err->request_id;
    }
}

v0.01 scope

• base URL handling
• default and per-request headers
• JSON request encoding
• JSON response decoding
• configurable timeout
• structured transport/HTTP/encode/decode errors
• extraction of Retry-After and common request-ID headers
• injectable transport for tests and custom integration

Planned

The next useful layers are retry with exponential backoff + jitter, pagination, rate-limit policy, and middleware/hooks. Those should remain opt-in and should not turn this module into another full HTTP stack.

Design principle

Keep the core small. Build on standard Perl HTTP/JSON components, provide stable API-client semantics, and make common production behavior easy to add without forcing a framework.

License

Same terms as Perl itself.