# 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

```perl
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

```perl
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.