view release on metacpan or  search on metacpan

t/API_Client.t  view on Meta::CPAN

=name

API::Client

=cut

=abstract

HTTP API Thin-Client Abstraction

=cut

=includes

method: create
method: delete
method: dispatch
method: fetch
method: patch
method: prepare
method: process
method: resource
method: serialize
method: update

=cut

=synopsis

  package main;

  use API::Client;

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

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

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

=cut

=libraries

Types::Standard

=cut

=integrates

Data::Object::Role::Buildable
Data::Object::Role::Stashable
Data::Object::Role::Throwable

=cut

=attributes

debug: ro, opt, Bool
fatal: ro, opt, Bool
logger: ro, opt, InstanceOf["FlightRecorder"]
name: ro, opt, Str
retries: ro, opt, Int
timeout: ro, opt, Int
url: ro, opt, InstanceOf["Mojo::URL"]
user_agent: ro, opt, InstanceOf["Mojo::UserAgent"]
version: ro, opt, Str

=cut

=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.

+=head1 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.

=cut

=scenario building

Building up an HTTP request is extremely easy, simply call the L</resource> to
create a new object instance representing the API endpoint you wish to issue a
request against.

=example 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]

=cut

=scenario chaining