NAME

Gcis::Client -- Perl client for interacting with the Global Change Information System

SYNOPSIS

    use Gcis::Client;

    my $c = Gcis::Client->new(url => 'http://data.globalchange.gov');
    print $c->get('/report');

    my $c = Gcis::Client->connect(url => $ARGV[0]);
    $c->post(
      '/report',
      {
        identifier       => 'my-new-report',
        title            => "awesome report",
        frequency        => "1 year",
        summary          => "this is a great report",
        report_type_identifier => "report",
        publication_year => '2000',
        url              => "http://example.com/report.pdf",
      }
    ) or die $c->error;

    # Add a chapter
    $c->post(
        "/report/my-new-report/chapter",
        {
            report_identifier => "my-new-report",
            identifier        => "my-chapter-identifier",
            title             => "Some Title",
            number            => 12,
            sort_key          => 100,
            doi               => '10.1234/567',
            url               => 'http://example.com/report',
        }
    ) or die $c->error;

    my $c = Gcis::Client->new
        ->url('http://data.globalchange.gov')
        ->logger($logger)
        ->find_credentials
        ->login;

DESCRIPTION

This is a simple client for the GCIS API, based on Mojo::UserAgent.

ATTRIBUTES

delay

A delay between requests.

url

The base url for the API.

key

An access key for the API.

error

An error from the most recent reqeust.

ua

The Mojo::UserAgent object.

logger

A logger (defaults to a Mojo::Log object).

accept

An accept header to send with every request (defaults to "application/json");

tx

The Mojo::Transaction object from the most recent request.

METHODS

connect

    my $c = Gcis::Client->connect(url => $url);

Shorthand for Gcis::Client->new->url($url)->find_credentials->login or die "Failed to log in to $url";

find_credentials

Matches a URL with one in the configuration file. See CONFIGURATION below.

login

Verify that a get request to /login succeeds.

Returns the client object if and only if it succeeds.

    $c->login;

get_chapter_map

Get a map from chapter number to identifer.

    my $identifier = $c->get_chapter_map('nca3')->{1}

use_env

Get the URL from the GCIS_API_URL environment variable. Also get an optional delay (in seconds) from GCIS_API_DELAY.

    $c->use_env;

get

Get a URL, requesting JSON, converting an arrayref to an array if called in an array context. An optional second parameter may be a hash which is converted into a query string.

    $gcis->get('/report');
    $gcis->get('/report', {report_type => 'assessment'});
    $gcis->get('/report?report_type=assessment');

add_file_url

Add a file using its URL.

    $c->add_file_url($gcid => {
        file_url => $file_url,
        landing_page => $landing_page
    });

put_file

PUT a local file to a remote destination.

    $g->put_file($destination, $source) or die $g->error;

    $path is the destination API path, like /report/files/nca2100/highres.pdf
    $source is the local file, e.g. /tmp/nca2100.pdf

CONFIGURATION

Credentials can be stored in a YAML file called ~/etc/Gcis.conf. This contains URLs and keys, in this format :

    - url      : http://data-stage.globalchange.gov
      userinfo : me@example.com:298015f752d99e789056ef826a7db7afc38a8bbd6e3e23b3
      key      : M2FiLTg2N2QtYjhiZTVhM5ZWEtYjNkM5ZWEtYjNkMS00LTgS00LTg2N2QtYZDFhzQyNGUxCg==

    - url      : http://data.globalchange.gov
      userinfo : username:pass
      key      : key

SEE ALSO

Mojo::UserAgent, Mojo::Log

cpanm Gcis::Client

perl -MCPAN -e shell
install Gcis::Client