view release on metacpan or  search on metacpan

lib/Restish/Client.pm  view on Meta::CPAN

    DELETE  => 1,
    PATCH   => 1,
    LIST    => 1,
);

# Set this to enable the canonical encoding of json, for facilitating string
# comparisons. Only to be used when testing. https://metacpan.org/pod/JSON#canonical
our $CANONICAL = 0;

=head1 NAME

Restish::Client - A RESTish client...in perl!

=head1 SYNOPSIS

    use Restish::Client;

    my $client = Restish::Client->new(
        uri_host            => 'https://api.example.com/',
        head_params_default => { 'Authorization' => 'Bearer mytoken' },
    );

    # GET request
    my $data = $client->GET( uri => '/v1/users' );

    # POST with body parameters
    my $result = $client->POST(
        uri         => '/v1/users',
        body_params => { name => 'Alice', email => 'alice@example.com' },
    );

    # GET with URI template and query parameters
    my $user = $client->GET(
        uri             => '/v1/users/%(user_id)s',
        template_params => { user_id => '42' },
        query_params    => { format => 'json' },
    );

    if ($client->response_code == 200) {
        print $user->{name};
    }

=head1 DESCRIPTION

This module provides a Perl wrapper for the REST-like API's.

=head2 METHODS

=over 12

=item C<new>

    my $client = Restish::Client->new(
        uri_host            => 'https://vault.example.com/',
        head_params_default => { 'X-Vault-Token' => $a_token },
        agent_options       => { timeout => 5 },
        require_https       => 1,
        ssl_opts => {
            SSL_use_cert    => 1,
            SSL_cert_file   => "/etc/ssl/certs/cert.pem",
            SSL_key_file    => "/etc/ssl/private_keys/key.pem",
        },
        cookie_jar          => 1,
    );

Construct a new Restish::Client object. The uri_host is used as the base
uri for each API call, and serves as a template if string interpolation is used
(see below). 

Optionally provide any data that can be set via a mutator, such as
head_params_default or the ssl_opts.

Options can be passed to the user agent (currently LWP) via agent_options.

If require_https is set, new() will die if uri_host is not an https uri. 

=item C<head_params_default>

    $client->head_params_default({ 'X-Vault-Token' => $auth_token });

Supply a hashref specifying default header parameters to be sent with every
request using this object.

=cut

has head_params_default => (
    is      => 'rw',
    default => sub { {} },
    isa     => sub { 
            __PACKAGE__->error("Invalid parameter $_[0]; supply a hashref")
                unless ref $_[0] eq 'HASH'
           }
);

=item C<ssl_opts>

    $client->ssl_opts({ SSL_use_cert => 1 });

Supply a hashref specifying default LWP UserAgent SSL options to be sent with every
request using this object.

=cut

has ssl_opts => (
    is      => 'rw',
    default => sub { {} },
    isa     => sub { 
            __PACKAGE__->error("Invalid parameter $_[0]; supply a hashref")
                unless ref $_[0] eq 'HASH'
           }
);

=item C<cookie_jar>

    $client->cookie_jar(1);
    $client->cookie_jar(/path/to/cookiejar)

Enable LWP UserAgent's cookie_jar.  Optionally store the cookie jar to disk.

=cut