/ 
WebService-GoogleAPI-Client-0.17
River stage zero No dependents
/ WebService::GoogleAPI::Client::Discovery

NAME

WebService::GoogleAPI::Client::Discovery - Google API discovery service

VERSION

version 0.17

MORE INFORMATION

https://developers.google.com/discovery/v1/reference/

SEE ALSO

Not using Swagger but it is interesting - https://github.com/APIs-guru/openapi-directory/tree/master/APIs/googleapis.com for Swagger Specs.

Google::API::Client - contains code for parsing discovery structures

includes a chi property that is an instance of CHI using File Driver to cache discovery resources for 30 days

say $client-dicovery->chi->root_dir(); ## provides full file path to temp storage location used for caching

TODO

  • handle 403 ( Daily Limit for Unauthenticated Use Exceeded.) errors when reqeusting a discovrey resource for a service but do we have access to authenticated reqeusts?

METHODS

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' );
my $hashref = $self->get_api_discovery_for_api_id( 'gmail:v3.users.list' );
my $hashref = $self->get_api_discovery_for_api_id( { api=> 'gmail', version => 'v3' } ); ## nb enclosing bracer - must be hashref

NB: if deeper structure than the api_id is provided then only the head is used

so get_api_discovery_for_api_id( 'gmail' ) is the same as get_api_discovery_for_api_id( 'gmail.some.child.method' )

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.

discover_all

TODO: Consider rename to return_fetched_google_v1_apis_discovery_structure

TODO - handle auth required error and resubmit request with OAUTH headers if response indicates access requires auth ( when exceed free access limits )

Return details about all Available Google APIs as provided by Google or in CHI Cache

On Success: Returns HASHREF with keys discoveryVersion,items,kind
On Failure: Warns and returns empty hashref

  my $d = WebService::GoogleAPI::Client::Discovery->new;
  print Dumper $d;

  WebService::GoogleAPI::Client::Discovery->discover_all();

  $client->discover_all();
  $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

SEE ALSO: available_APIs, list_of_available_google_api_ids

augment_discover_all_with_unlisted_experimental_api

Allows you to augment the cached stored version of the discovery structure

augment_discover_all_with_unlisted_experimental_api( 
                        {
                          'version' => 'v4',
                          'preferred' => 1,
                          'title' => 'Google My Business API',
                          'description' => 'The Google My Business API provides an interface for managing business location information on Google.',
                          'id' => 'mybusiness:v4',
                          'kind' => 'discovery#directoryItem',
                          'documentationLink' => "https://developers.google.com/my-business/",
                          'icons' => {
                                     "x16"=> "http://www.google.com/images/icons/product/search-16.gif",
                                     "x32"=> "http://www.google.com/images/icons/product/search-32.gif"
                                   },
                          'discoveryRestUrl' =>
   'https://developers.google.com/my-business/samples/mybusiness_google_rest_v4p2.json',
                          'name' => 'mybusiness'
                        }   );

if there is a conflict with the existing then warn and return the existing data without modification

on success just returns the augmented structure

NB - does not interpolate schema object '$ref' values.

available_APIs

Return arrayref of all available API's (services)

{
  'name' => 'youtube',
  'versions' => [ 'v3' ]
  documentationLink =>  ,
  discoveryRestUrl =>  ,
},

Originally for printing list of supported API's in documentation ..

SEE ALSO: may be better/more flexible to use client->list_of_available_google_api_ids client->discover_all which is delegated to Client::Discovery->discover_all

service_exists

Return 1 if Google Service API ID is described by Google API discovery. 
Otherwise return 0

 print $d->service_exists('calendar');  # 1
 print $d->service_exists('someapi');  # 0

NB - Is case sensitive - all lower is required so $d->service_exists('Calendar') returns 0

supported_as_text

No params.
Returns list of supported APIs as string in human-readible format ( name, versions and doclinks )

available_versions

Show available versions of particular API described by api id passed as parameter such as 'gmail'

$d->available_versions('calendar');  # ['v3']
$d->available_versions('youtubeAnalytics');  # ['v1','v1beta1']

Returns arrayref

latest_stable_version

return latest stable verion of API

$d->available_versions('calendar');  # ['v3']
$d->latest_stable_version('calendar');  # 'v3'

$d->available_versions('tagmanager');  # ['v1','v2']
$d->latest_stable_version('tagmanager');  # ['v2']

$d->available_versions('storage');  # ['v1','v1beta1', 'v1beta2']
$d->latest_stable_version('storage');  # ['v1']

extract_method_discovery_detail_from_api_spec

$agent->extract_method_discovery_detail_from_api_spec( $tree, $api_version )

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

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.users.settings.delegates.get');

methods_available_for_google_api_id('gmail.users.settings.delegates.get', 'v1');

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();

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