view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# NAME

API::Client

# ABSTRACT

HTTP API Thin-Client Abstraction

# SYNOPSIS

    package main;

    use API::Client;

    my $client = API::Client->new(url => 'https://httpbin.org');

    # $client->resource('post');

    # $client->update(json => {...});

# DESCRIPTION

This package provides an abstraction and method for rapidly developing HTTP API
clients. While this module can be used to interact with APIs directly,
API::Client was designed to be consumed (subclassed) by higher-level
purpose-specific API clients.

# THIN CLIENT

The thin API client library is advantageous as it has complete API coverage and
can easily adapt to changes in the API with minimal effort. As a thin-client
superclass, this module does not map specific HTTP requests to specific
routines, nor does it provide parameter validation, pagination, or other
conventions found in typical API client implementations; Instead, it simply
provides a simple and consistent mechanism for dynamically generating HTTP
requests.  Additionally, this module has support for debugging and retrying API
calls as well as throwing exceptions when 4xx and 5xx server response codes are
returned.

# INTEGRATES

This package integrates behaviors from:

[Data::Object::Role::Buildable](https://metacpan.org/pod/Data::Object::Role::Buildable)

[Data::Object::Role::Stashable](https://metacpan.org/pod/Data::Object::Role::Stashable)

[Data::Object::Role::Throwable](https://metacpan.org/pod/Data::Object::Role::Throwable)

# LIBRARIES

This package uses type constraints from:

[Types::Standard](https://metacpan.org/pod/Types::Standard)

# SCENARIOS

This package supports the following scenarios:

## building

    # given: synopsis

    my $resource = $client->resource('get');

    # GET /get
    my $get = $client->resource('get')->dispatch;

    # HEAD /head
    my $head = $client->resource('head')->dispatch(
      method => 'head'
    );

    # PATCH /patch
    my $patch = $client->resource('patch')->dispatch(
      method => 'patch'
    );

    [$get, $head, $patch]

Building up an HTTP request is extremely easy, simply call the ["resource"](#resource) to
create a new object instance representing the API endpoint you wish to issue a
request against.

## chaining

    # given: synopsis

    # https://httpbin.org/users
    my $users = $client->resource('users');

    # https://httpbin.org/users/c09e91a
    my $user = $client->resource('users', 'c09e91a');

    # https://httpbin.org/users/c09e91a
    my $new_user = $users->resource('c09e91a');

README.md  view on Meta::CPAN

    }

    package main;

    my $hookbin = Hookbin->new;

This package was designed to be subclassed and provides hooks into the client
building and request dispatching processes. Specifically, there are three
useful hooks (i.e. methods, which if present are used to build up the client
object and requests), which are, the `auth` hook, which should return a
`Tuple[Str, Str]` which is used to configure the basic auth header, the
`base` hook which should return a `Tuple[Str]` which is used to configure the
base URL, and the `headers` hook, which should return a
`ArrayRef[Tuple[Str, Str]]` which are used to configure the HTTP request
headers.

## transacting

    # given: synopsis

    my $tx1 = $client->resource('patch')->patch(
      json => {active => 1}
    );

    # is equivalent to

    my $tx2 = $client->resource('patch')->dispatch(
      method => 'patch',
      json => {active => 1}
    );

    [$tx1, $tx2]

An HTTP request is only issued when the ["dispatch"](#dispatch) method is called, directly
or indirectly. Those calls return a [Mojo::Transaction](https://metacpan.org/pod/Mojo::Transaction) object which provides
access to the `request` and `response` objects.

## updating

    # given: synopsis

    my $tx1 = $client->resource('put')->update(
      json => {active => 1}
    );

    # is equivalent to

    my $tx2 = $client->resource('put')->dispatch(
      method => 'put',
      json => {active => 1}
    );

    [$tx1, $tx2]

This example illustrates how you might update a new API resource.

# ATTRIBUTES

This package has the following attributes:

## debug

    debug(Bool)

This attribute is read-only, accepts `(Bool)` values, and is optional.

## fatal

    fatal(Bool)

This attribute is read-only, accepts `(Bool)` values, and is optional.

## logger

    logger(InstanceOf["FlightRecorder"])

This attribute is read-only, accepts `(InstanceOf["FlightRecorder"])` values, and is optional.

## name

    name(Str)

This attribute is read-only, accepts `(Str)` values, and is optional.

## retries

    retries(Int)

This attribute is read-only, accepts `(Int)` values, and is optional.

## timeout

    timeout(Int)

This attribute is read-only, accepts `(Int)` values, and is optional.

## url

    url(InstanceOf["Mojo::URL"])

This attribute is read-only, accepts `(InstanceOf["Mojo::URL"])` values, and is optional.

## user\_agent

    user_agent(InstanceOf["Mojo::UserAgent"])

This attribute is read-only, accepts `(InstanceOf["Mojo::UserAgent"])` values, and is optional.

## version

    version(Str)

This attribute is read-only, accepts `(Str)` values, and is optional.

# METHODS

This package implements the following methods:

## create

    create(Any %args) : InstanceOf["Mojo::Transaction"]

The create method issues a `POST` request to the API resource represented by