NAME
HTTP::API::Core - Small foundation for JSON HTTP API clients
SYNOPSIS
use HTTP::API::Core;
my $api = HTTP::API::Core->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,
},
hooks => {
before_request => sub {
my ($ctx) = @_;
$ctx->{headers}{'X-Trace-Id'} = make_trace_id();
},
},
);
my $response = $api->get('/users');
my $users = $response->json;
my $rate = $response->rate_limit;
my $pager = $api->paginate(
'/users',
mode => 'cursor',
items => 'data.users',
next => 'meta.next_cursor',
);
while (my $user = $pager->next) {
...
}DESCRIPTION
HTTP::API::Core 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, conservative retries, pagination helpers, normalized rate-limit metadata, and lifecycle hooks.
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, 5xx responses, and 403 responses that explicitly report an exhausted rate limit.
METHODS
new
my $api = HTTP::API::Core->new(
base_url => 'https://api.example.com',
headers => { ... },
timeout => 10,
retry => { attempts => 3 },
hooks => { ... },
);base_url is required. headers, timeout, retry, and hooks are optional. Retry defaults to three attempts with exponential backoff and jitter.
get, post, put, patch, delete
Convenience methods around request.
paginate
Returns an HTTP::API::Core::Pagination iterator. Supported modes are next_url, page, and cursor.
request
Pass json to encode a Perl value as JSON, or content to send raw content. Pass query as a hash reference to append percent-encoded query parameters. Array-reference values produce repeated keys and undefined values are omitted. Per-request headers override default headers. Pass retry => 0 to disable retry for one request, or a retry hash to override the policy. A hooks hash can add request-local hooks after client-level hooks.
Non-2xx responses throw HTTP::API::Core::Error after retry is exhausted. Successful responses expose normalized rate-limit metadata through $response->rate_limit.
HOOKS
Hooks may be configured on the client or per request. Supported hook names are before_request, after_response, and on_error. Each value may be a coderef or an arrayref of coderefs.
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.
RATE LIMITS
HTTP::API::Core::RateLimit normalizes RateLimit-*, X-RateLimit-*, and Retry-After response headers.
ERROR HANDLING
Errors expose stable fields such as category, status, method, url, retryable, retry_after, request_id, and rate_limit.
TRANSPORT CONTRACT
The transport constructor option accepts either a code reference or an object with a request method. Both are called as request($method, $url, \%options) and must return a hash reference containing at least status, with optional reason, headers, and content fields.
IDEMPOTENCY
Pass idempotency => { key => ..., header => ... } to add an API-specific idempotency-key header to a request. The core deliberately does not assume a universal header name.
LICENSE
This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.