API-Client
view release on metacpan or search on metacpan
received the program in object code or executable form alone.)
Source code for a work means the preferred form of the work for making
modifications to it. For an executable file, complete source code means
all the source code for all modules it contains; but, as a special
exception, it need not include source code for modules which are standard
libraries that accompany the operating system on which the executable
file runs, or for standard header files or definitions files that
accompany that operating system.
4. You may not copy, modify, sublicense, distribute or transfer the
Program except as expressly provided under this General Public License.
Any attempt otherwise to copy, modify, sublicense, distribute or transfer
the Program is void, and will automatically terminate your rights to use
the Program under this License. However, parties who have received
copies, or rights to use copies, from you under this General Public
License will not have their licenses terminated so long as such parties
remain in full compliance.
5. By copying, distributing or modifying the Program (or any work based
on the Program) you indicate your acceptance of this license to do so,
and all its terms and conditions.
6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the original
licensor to copy, distribute or modify the Program subject to these
terms and conditions. You may not impose any further restrictions on the
recipients' exercise of the rights granted herein.
7. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the Program
specifies a version number of the license which applies to it and "any
may not charge a fee for this Package itself. However, you may distribute this
Package in aggregate with other (possibly commercial) programs as part of a
larger (possibly commercial) software distribution provided that you do not
advertise this Package as a product of your own.
6. The scripts and library files supplied as input to or produced as output
from the programs of this Package do not automatically fall under the copyright
of this Package, but belong to whomever generated them, and may be sold
commercially, and may be aggregated with this Package.
7. C or perl subroutines supplied by you and linked into this Package shall not
be considered part of this Package.
8. The name of the Copyright Holder may not be used to endorse or promote
products derived from this software without specific prior written permission.
9. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
The End
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
my $tx2 = $client->resource('get')->dispatch(
method => 'get',
query => {active => 1}
);
[$tx1, $tx2]
This example illustrates how you might fetch an API resource.
subclassing
package Hookbin;
use Data::Object::Class;
extends 'API::Client';
sub auth {
['admin', 'secret']
}
sub headers {
[['Accept', '*/*']]
}
sub base {
['https://httpbin.org/get']
}
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
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
my $tx2 = $client->resource('get')->dispatch(
method => 'get',
query => {active => 1}
);
[$tx1, $tx2]
This example illustrates how you might fetch an API resource.
## subclassing
package Hookbin;
use Data::Object::Class;
extends 'API::Client';
sub auth {
['admin', 'secret']
}
sub headers {
[['Accept', '*/*']]
}
sub base {
['https://httpbin.org/get']
}
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
requires "Data::Object::Role::Buildable" => "0.03";
requires "Data::Object::Role::Stashable" => "2.01";
requires "Data::Object::Role::Throwable" => "2.01";
requires "FlightRecorder" => "0.03";
requires "Mojolicious" => "8.35";
requires "perl" => "5.014";
requires "routines" => "0";
requires "strict" => "0";
requires "warnings" => "0";
on 'test' => sub {
requires "Data::Object::Class" => "2.02";
requires "Data::Object::ClassHas" => "2.01";
requires "Data::Object::Role::Buildable" => "0.03";
requires "Data::Object::Role::Stashable" => "2.01";
requires "Data::Object::Role::Throwable" => "2.01";
requires "FlightRecorder" => "0.03";
requires "Mojolicious" => "8.35";
requires "Test::Auto" => "0.10";
requires "perl" => "5.014";
requires "routines" => "0";
requires "strict" => "0";
requires "warnings" => "0";
};
on 'configure' => sub {
requires "ExtUtils::MakeMaker" => "0";
};
lib/API/Client.pm view on Meta::CPAN
# $client->resource('post');
# $client->update(json => {...});
=cut
=head1 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
lib/API/Client.pm view on Meta::CPAN
method => 'get',
query => {active => 1}
);
[$tx1, $tx2]
This example illustrates how you might fetch an API resource.
=cut
=head2 subclassing
package Hookbin;
use Data::Object::Class;
extends 'API::Client';
sub auth {
['admin', 'secret']
}
sub headers {
[['Accept', '*/*']]
}
sub base {
['https://httpbin.org/get']
}
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 C<auth> hook, which should return a
C<Tuple[Str, Str]> which is used to configure the basic auth header, the
C<base> hook which should return a C<Tuple[Str]> which is used to configure the
base URL, and the C<headers> hook, which should return a
C<ArrayRef[Tuple[Str, Str]]> which are used to configure the HTTP request
headers.
=cut
t/API_Client.t view on Meta::CPAN
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
t/API_Client.t view on Meta::CPAN
my $tx2 = $client->resource('patch')->dispatch(
method => 'patch',
json => {active => 1}
);
[$tx1, $tx2]
=cut
=scenario subclassing
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 C<auth> hook, which should return a
C<Tuple[Str, Str]> which is used to configure the basic auth header, the
C<base> hook which should return a C<Tuple[Str]> which is used to configure the
base URL, and the C<headers> hook, which should return a
C<ArrayRef[Tuple[Str, Str]]> which are used to configure the HTTP request
headers.
=example subclassing
package Hookbin;
use Data::Object::Class;
extends 'API::Client';
sub auth {
['admin', 'secret']
}
sub headers {
[['Accept', '*/*']]
}
sub base {
['https://httpbin.org/get']
}
package main;
my $hookbin = Hookbin->new;
=cut
=method dispatch
t/API_Client.t view on Meta::CPAN
SKIP: {
my $skip_tests = do {
my $tx = Mojo::UserAgent->new->get('https://httpbin.org/anything');
!eval{$tx->result->is_success};
};
unless ($skip_tests) {
my $test = testauto(__FILE__);
my $subs = $test->standard;
$subs->synopsis(fun($tryable) {
ok my $result = $tryable->result;
$result
});
$subs->scenario('building', fun($tryable) {
require Scalar::Util;
ok my $result = $tryable->result;
my $get = $result->[0];
my $head = $result->[1];
my $patch = $result->[2];
isnt Scalar::Util::refaddr($get), Scalar::Util::refaddr($head);
isnt Scalar::Util::refaddr($get), Scalar::Util::refaddr($patch);
isnt Scalar::Util::refaddr($head), Scalar::Util::refaddr($patch);
is $get->req->method, 'get';
is $head->req->method, 'head';
is $patch->req->method, 'patch';
});
$subs->scenario('chaining', fun($tryable) {
require Scalar::Util;
ok my $result = $tryable->result;
my $users = $result->[0];
my $user = $result->[1];
my $new_user = $result->[2];
isnt Scalar::Util::refaddr($users), Scalar::Util::refaddr($user);
isnt Scalar::Util::refaddr($users), Scalar::Util::refaddr($new_user);
isnt Scalar::Util::refaddr($user), Scalar::Util::refaddr($new_user);
is $users->url->to_string, 'https://httpbin.org/users';
is $user->url->to_string, 'https://httpbin.org/users/c09e91a';
is $new_user->url->to_string, 'https://httpbin.org/users/c09e91a';
});
$subs->scenario('fetching', fun($tryable) {
ok my $result = $tryable->result;
;
});
$subs->scenario('creating', fun($tryable) {
ok my $result = $tryable->result;
;
});
$subs->scenario('updating', fun($tryable) {
ok my $result = $tryable->result;
;
});
$subs->scenario('deleting', fun($tryable) {
ok my $result = $tryable->result;
;
});
$subs->scenario('transacting', fun($tryable) {
ok my $result = $tryable->result;
;
});
$subs->scenario('subclassing', fun($tryable) {
ok my $result = $tryable->result;
ok $result->isa('Hookbin');
ok $result->isa('API::Client');
is_deeply $result->auth, ['admin', 'secret'];
is_deeply $result->headers, [['Accept', '*/*']];
is_deeply $result->base, ['https://httpbin.org/get'];
is $result->url->to_string, 'https://httpbin.org/get';
is $result->name, 'Hookbin (0.01)';
});
$subs->example(-1, 'create', 'method', fun($tryable) {
ok my $result = $tryable->result;
my $req = $result->req;
is lc($req->method), 'post';
my $res = $result->res;
is $res->code, 200;
my $json = $res->json;
is $json->{headers}{'Host'}, 'httpbin.org';
is $json->{headers}{'Content-Type'}, 'application/json';
is_deeply $json->{json}, {active => 1};
$result
});
$subs->example(-1, 'delete', 'method', fun($tryable) {
ok my $result = $tryable->result;
my $req = $result->req;
is lc($req->method), 'delete';
my $res = $result->res;
is $res->code, 200;
my $json = $res->json;
is $json->{headers}{'Host'}, 'httpbin.org';
is $json->{headers}{'Content-Type'}, 'application/json';
is_deeply $json->{json}, undef;
is_deeply $json->{form}, {};
is $json->{data}, '';
$result
});
$subs->example(-1, 'dispatch', 'method', fun($tryable) {
ok my $result = $tryable->result;
my $req = $result->req;
is lc($req->method), 'get';
my $res = $result->res;
is $res->code, 200;
my $json = $res->json;
is $json->{headers}{'Host'}, 'httpbin.org';
is $json->{headers}{'Content-Type'}, 'application/json';
is_deeply $json->{args}, {};
$result
});
$subs->example(-2, 'dispatch', 'method', fun($tryable) {
ok my $result = $tryable->result;
my $req = $result->req;
is lc($req->method), 'post';
my $res = $result->res;
is $res->code, 200;
my $json = $res->json;
is $json->{headers}{'Host'}, 'httpbin.org';
is $json->{headers}{'Content-Type'}, 'application/json';
is $json->{data}, "active=1";
$result
});
$subs->example(-3, 'dispatch', 'method', fun($tryable) {
ok my $result = $tryable->result;
my $req = $result->req;
is lc($req->method), 'get';
my $res = $result->res;
is $res->code, 200;
my $json = $res->json;
is $json->{headers}{'Host'}, 'httpbin.org';
is $json->{headers}{'Content-Type'}, 'application/json';
is_deeply $json->{args}, {active => 1};
$result
});
$subs->example(-4, 'dispatch', 'method', fun($tryable) {
ok my $result = $tryable->result;
my $req = $result->req;
is lc($req->method), 'post';
my $res = $result->res;
is $res->code, 200;
my $json = $res->json;
is $json->{headers}{'Host'}, 'httpbin.org';
is $json->{headers}{'Content-Type'}, 'application/json';
is_deeply $json->{json}, {active => 1};
$result
});
$subs->example(-5, 'dispatch', 'method', fun($tryable) {
ok my $result = $tryable->result;
my $req = $result->req;
is lc($req->method), 'post';
my $res = $result->res;
is $res->code, 200;
my $json = $res->json;
is $json->{headers}{'Host'}, 'httpbin.org';
is $json->{headers}{'Content-Type'}, 'application/json';
is $json->{data}, "active=1";
$result
});
$subs->example(-6, 'dispatch', 'method', fun($tryable) {
ok my $result = $tryable->result;
my $req = $result->req;
is lc($req->method), 'put';
my $res = $result->res;
is $res->code, 200;
my $json = $res->json;
is $json->{headers}{'Host'}, 'httpbin.org';
is $json->{headers}{'Content-Type'}, 'application/json';
is_deeply $json->{json}, {active => 1};
$result
});
$subs->example(-7, 'dispatch', 'method', fun($tryable) {
ok my $result = $tryable->result;
my $req = $result->req;
is lc($req->method), 'patch';
my $res = $result->res;
is $res->code, 200;
my $json = $res->json;
is $json->{headers}{'Host'}, 'httpbin.org';
is $json->{headers}{'Content-Type'}, 'application/json';
is_deeply $json->{json}, {active => 1};
$result
});
$subs->example(-8, 'dispatch', 'method', fun($tryable) {
ok my $result = $tryable->result;
my $req = $result->req;
is lc($req->method), 'delete';
my $res = $result->res;
is $res->code, 200;
my $json = $res->json;
is $json->{headers}{'Host'}, 'httpbin.org';
is $json->{headers}{'Content-Type'}, 'application/json';
is_deeply $json->{json}, {active => 1};
$result
});
$subs->example(-1, 'fetch', 'method', fun($tryable) {
ok my $result = $tryable->result;
my $req = $result->req;
is lc($req->method), 'get';
my $res = $result->res;
is $res->code, 200;
my $json = $res->json;
is $json->{headers}{'Host'}, 'httpbin.org';
is $json->{headers}{'Content-Type'}, 'application/json';
is_deeply $json->{json}, undef;
is_deeply $json->{form}, undef;
is $json->{data}, undef;
$result
});
$subs->example(-1, 'patch', 'method', fun($tryable) {
ok my $result = $tryable->result;
my $req = $result->req;
is lc($req->method), 'patch';
my $res = $result->res;
is $res->code, 200;
my $json = $res->json;
is $json->{headers}{'Host'}, 'httpbin.org';
is $json->{headers}{'Content-Type'}, 'application/json';
is_deeply $json->{json}, {active => 1};
$result
});
$subs->example(-1, 'prepare', 'method', fun($tryable) {
ok my $result = $tryable->result;
$result
});
$subs->example(-1, 'process', 'method', fun($tryable) {
ok my $result = $tryable->result;
$result
});
$subs->example(-1, 'resource', 'method', fun($tryable) {
ok my $result = $tryable->result;
is $result->debug, 0;
is $result->fatal, 0;
like $result->name, qr/API::Client \(\d.\d\d\)/;
is $result->retries, 0;
is $result->timeout, 10;
is $result->url->to_string, 'https://httpbin.org/status/200';
$result
});
$subs->example(-1, 'serialize', 'method', fun($tryable) {
ok my $result = $tryable->result;
is $result->{debug}, 0;
is $result->{fatal}, 0;
like $result->{name}, qr/API::Client \(\d.\d\d\)/;
is $result->{retries}, 0;
is $result->{timeout}, 10;
is $result->{url}, 'https://httpbin.org';
$result
});
$subs->example(-1, 'update', 'method', fun($tryable) {
ok my $result = $tryable->result;
my $req = $result->req;
is lc($req->method), 'put';
my $res = $result->res;
is $res->code, 200;
my $json = $res->json;
is $json->{headers}{'Host'}, 'httpbin.org';
( run in 0.350 second using v1.01-cache-2.11-cpan-88abd93f124 )