README.txt

NAME

    WebService::GoogleAPI::Client - Google API Discovery and SDK

VERSION

    version 0.21

SYNOPSIS

    Access Google API Services Version 1 using an OAUTH2 User Agent.

    Includes Discovery, validation authentication and API Access.

    assumes gapi.json configuration in working directory with scoped Google
    project redentials and user authorization created by _goauth_

        use WebService::GoogleAPI::Client;
        
        my $gapi_client = WebService::GoogleAPI::Client->new( debug => 1, gapi_json => 'gapi.json', user=> 'peter@pscott.com.au' );
        
        say $gapi_client->list_of_available_google_api_ids();
    
        my @gmail_endpoint_list =      $gapi_client->methods_available_for_google_api_id('gmail')
    
        if $gapi_agent->has_scope_to_access_api_endpoint( 'gmail.users.settings.sendAs.get' ) {
          say 'User has Access to GMail Method End-Point gmail.users.settings.sendAs.get';
        }

    Internal User Agent provided be property
    WebService::GoogleAPI::Client::UserAgent dervied from Mojo::UserAgent

    Package includes go_auth CLI Script to collect initial end-user
    authorisation to scoped services

EXAMPLES

 AUTOMATIC API REQUEST CONSTRUCTION - SEND EMAL

        ## using dotted API Endpoint id to invoke helper validation and default value interpolations etc to send email to self
        use Email::Simple;    ## RFC2822 formatted messages
        use MIME::Base64;
        my $my_email_address = 'peter@shotgundriver.com'
    
    
        my $raw_email_payload = encode_base64( Email::Simple->create( header => [To => $my_email_address, 
                                                                                 From => $my_email_address, 
                                                                                 Subject =>"Test email from '$my_email_address' ",], 
                                                                                 body => "This is the body of email to '$my_email_address'", 
                                                                    )->as_string 
                                            );
    
        $gapi_client->api_query( 
                                api_endpoint_id => 'gmail.users.messages.send',
                                options    => { raw => $raw_email_payload },
                            );

 MANUAL API REQUEST CONSTRUCTION - GET CALENDAR LIST

        ## Completely manually constructed API End-Point Request to obtain Perl Data Structure converted from JSON response.
        my $res = $gapi_client->api_query(
          method => 'get',
          path => 'https://www.googleapis.com/calendar/users/me/calendarList',
        )->json;

METHODS

 new

      WebService::GoogleAPI::Client->new( user => 'peter@pscott.com.au', gapi_json => '/fullpath/gapi.json' );

  PARAMETERS

   user :: the email address that identifies key of credentials in the
   config file

   gapi_json :: Location of the configuration credentials - default
   gapi.json

   debug :: if '1' then diagnostics are send to STDERR - default false

   chi :: an instance to a CHI persistent storage case object - if none
   provided FILE is used

 api_query

    query Google API with option to validate request before submitting

    handles user auth token inclusion in request headers and refreshes
    token if required and possible

    Required params: method, route

    Optional params: api_endpoint_id cb_method_discovery_modify

    $self->access_token must be valid

      $gapi->api_query({
          method => 'get',
          path => 'https://www.googleapis.com/calendar/users/me/calendarList',
        });
    
      $gapi->api_query({
          method => 'post',
          path => 'https://www.googleapis.com/calendar/v3/calendars/'.$calendar_id.'/events',
          options => { key => value }
      }
    
      ## if provide the Google API Endpoint to inform pre-query validation
      say $gapi_agent->api_query(
          api_endpoint_id => 'gmail.users.messages.send',
          options    => { raw => encode_base64( 
                                                Email::Simple->create( header => [To => $user, From => $user, Subject =>"Test email from $user",], 
                                                                        body   => "This is the body of email from $user to $user", )->as_string 
                                              ), 
                        },
      )->to_string; ##
    
      print  $gapi_agent->api_query(
                api_endpoint_id => 'gmail.users.messages.list', ## auto sets method to GET, path to 'https://www.googleapis.com/calendar'
              )->to_string;
      #print pp $r;
    
    
      if the pre-query validation fails then a 418 - I'm a Teapot error response is returned with the 
      body containing the specific description of the errors ( Tea Leaves ;^) ).   

    NB: If you pass a 'path' parameter this takes precendence over the API
    Discovery Spec. Any parameters defined in the path of the format
    {VARNAME} will be filled in with values within the options=>{ VARNAME
    => 'value '} parameter structure. This is the simplest way of
    addressing issues where the API discovery spec is inaccurate. ( See
    dev_sheets_example.pl as at 14/11/18 for illustration )

    To allow the user to fix discrepencies in the Discovery Specification
    the cb_method_discovery_modify callback can be used which must accept
    the method specification as a parameter and must return a (potentially
    modified) method spec.

    eg.

        my $r = $gapi_client->api_query(  api_endpoint_id => "sheets:v4.spreadsheets.values.update",  
                                        options => { 
                                          spreadsheetId => '1111111111111111111',
                                          valueInputOption => 'RAW',
                                          range => 'Sheet1!A1:A2',
                                          'values' => [[99],[98]]
                                        },
                                        cb_method_discovery_modify => sub { 
                                          my  $meth_spec  = shift; 
                                          $meth_spec->{parameters}{valueInputOption}{location} = 'path';
                                          $meth_spec->{path} = "v4/spreadsheets/{spreadsheetId}/values/{range}?valueInputOption={valueInputOption}";
                                          return $meth_spec;
                                        }
                                        );

    Returns Mojo::Message::Response object

 has_scope_to_access_api_endpoint

    Given an API Endpoint such as 'gmail.users.settings.sendAs.get' returns
    1 iff user has scope to access

        say 'User has Access'  if $gapi_agent->has_scope_to_access_api_endpoint( 'gmail.users.settings.sendAs.get' );

    Returns 0 if scope to access is not available to the user.

    warns and returns 0 on error ( eg user or config not specified etc )

METHODS DELEGATED TO WebService::GoogleAPI::Client::Discovery

 discover_all

      Return details about all Available Google APIs as provided by Google or in CHI Cache
    
      On Success: Returns HASHREF containing items key => list of hashes describing each API
      On Failure: Warns and returns empty hashref
    
        my $client = WebService::GoogleAPI::Client->new; ## has discovery member WebService::GoogleAPI::Client::Discovery
    
        $d = $client->discover_all();
        $d = $client->discover_all(1); ## NB if include a parameter that evaluates to true such as '1' then the cache is flushed with a new version
    
        ## OR
        $d = $client->discovery-> discover_all();
        $d = WebService::GoogleAPI::Client::Discovery->discover_all();
    
        print Dumper $d;
    
          $VAR1 = {
                    'items' => [
                                {
                                  'preferred' => bless( do{\(my $o = 1)}, 'JSON::PP::Boolean' ),
                                  'id' => 'abusiveexperiencereport:v1',
                                  'icons' => {
                                                'x32' => 'https://www.gstatic.com/images/branding/product/1x/googleg_32dp.png',
                                                'x16' => 'https://www.gstatic.com/images/branding/product/1x/googleg_16dp.png'
                                              },
                                  'version' => 'v1',
                                  'documentationLink' => 'https://developers.google.com/abusive-experience-report/',
                                  'kind' => 'discovery#directoryItem',
                                  'discoveryRestUrl' => 'https://abusiveexperiencereport.googleapis.com/$discovery/rest?version=v1',
                                  'title' => 'Abusive Experience Report API',
                                  'name' => 'abusiveexperiencereport',
                                  'description' => 'Views Abusive Experience Report data, and gets a list of sites that have a significant number of abusive experiences.'
                                }, ...
    
        ## NB because the structure isn't indexed on the api name it can be convenient to post-process it
        ## 
        
        my $new_hash = {};
        foreach my $api ( @{ %{$client->discover_all()}{items} } )
        {
            # convert JSON::PP::Boolean to true|false strings
            $api->{preferred}  = "$api->{preferred}" if defined $api->{preferred};
            $api->{preferred}  = $api->{preferred} eq '0' ? 'false' : 'true';
    
            $new_hash->{ $api->{name} } = $api;
        }
        print dump $new_hash->{gmail};

 get_api_discovery_for_api_id

    returns the cached version if avaiable in CHI otherwise retrieves
    discovery data via HTTP, stores in CHI cache and returns as a Perl data
    structure.

        my $hashref = $self->get_api_discovery_for_api_id( 'gmail' );
        my $hashref = $self->get_api_discovery_for_api_id( 'gmail:v3' );

    returns the api discovery specification structure ( cached by CHI ) for
    api id ( eg 'gmail ')

    returns the discovery data as a hashref, an empty hashref on certain
    failing conditions or croaks on critical errors.

 methods_available_for_google_api_id

    Returns a hashref keyed on the Google service API Endpoint in dotted
    format. The hashed content contains a structure representing the
    corresponding discovery specification for that method ( API Endpoint ).

        methods_available_for_google_api_id('gmail')

 extract_method_discovery_detail_from_api_spec

        $my $api_detail = $gapi->discovery->extract_method_discovery_detail_from_api_spec( 'gmail.users.settings' );

    returns a hashref representing the discovery specification for the
    method identified by $tree in dotted API format such as
    texttospeech.text.synthesize

    returns an empty hashref if not found

 list_of_available_google_api_ids

    Returns an array list of all the available API's described in the API
    Discovery Resource that is either fetched or cached in CHI locally for
    30 days.

        my $r = $agent->list_of_available_google_api_ids();
        print "List of API Services ( comma separated): $r\n";
    
        my @list = $agent->list_of_available_google_api_ids();

FEATURES

      * API Discovery requests cached with CHI ( Default File )

      * OAUTH app and user credentials (client_id, client_secret, scope,
      users access_token and refresh_tokens) stored in local file (default
      name = gapi.json)

      * access_token auto-refreshes when expires (if user has
      refresh_token) saving refreshed token back to json file

      * helper api_query to streamline request composition without
      preventing manual construction if preferred.

      * CLI tool (goauth) with lightweight Mojo HTTP server to simplify
      OAuth2 configuration, sccoping, authorization and obtaining access_
      and refresh_ tokens from users

AUTHOR

    Peter Scott <localshop@cpan.org>

COPYRIGHT AND LICENSE

    This software is Copyright (c) 2017-2018 by Peter Scott and others.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004