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

NAME

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

VERSION

version 0.27

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.

WebService::GoogleAPI::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

METHODS

get_with_cache

my $hashref = $disco->get_with_cache($url, $force, $authenticate)

Retrieves the given API URL, retrieving and caching the returned JSON. If it gets a 403 Unauthenticated error, then it will try again using the credentials that are save on this instances 'ua'.

If passed a truthy value for $force, then will not use the cache. If passed a truthy value for $authenticate, then will make the request with credentials.

discover_all

my $hashref = $disco->discover_all($force, $authenticate)

Return details about all Available Google APIs as provided by Google or in CHI Cache. Does the fetching with get_with_cache, and arguments are as above.

On Success: Returns HASHREF with keys discoveryVersion,items,kind On Failure: dies a horrible death. You probably don't want to continue in that case.

SEE ALSO: available_APIs, list_of_available_google_api_ids

available_APIs

Return hashref keyed on api name, with arrays of versions, links to documentation, and links to the url for that version's API document.

{
  youtube => {
    version           => [ 'v3', ... ]
    documentationLink => [ ...,  ... ] ,
    discoveryRestUrl  => [ ...,  ... ] ,
  },
  gmail => {
    ...
  } 
}

Used internally to pull relevant discovery documents.

augment_with

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

$augmented_document = $disco->augment_with({
  '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'
});

This can also be used to overwrite the cached structure.

Can also be called as augment_discover_all_with_unlisted_experimental_api, which is being deprecated for being plain old too long.

service_exists

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

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

Note that most Google APIs are fully lowercase, but some are camelCase. Please check the documentation from Google for reference.

available_versions

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

$disco->available_versions('calendar');  # ['v3']
$disco->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']

process_api_version

my $hashref = $disco->process_api_version('gmail')   
   # { api => 'gmail', version => 'v1' }
my $hashref = $disco->process_api_version({ api => 'gmail' })   
   # { api => 'gmail', version => 'v1' }
my $hashref = $disco->process_api_version('gmail:v2') 
   # { api => 'gmail', version 'v2' }

Takes a version string and breaks it into a hashref. If no version is given, then default to the latest stable version in the discover document.

get_api_document

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_document( 'gmail' );
my $hashref = $self->get_api_document( 'gmail:v3' );
my $hashref = $self->get_api_document( 'gmail:v3.users.list' );
my $hashref = $self->get_api_document( { api=> 'gmail', version => 'v3' } );

NB: if deeper structure than the api_id is provided then only the head is used so get_api_document( 'gmail' ) is the same as get_api_document( '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.

Also available as get_api_discovery_for_api_id, which is being deprecated.

get_method_details

$disco->get_method_details($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

Dies a horrible death if not found.

Also available as extract_method_discovery_detail_from_api_spec, but the long name is being deprecated in favor of the more compact one.

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_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_api_ids();
print "List of API Services ( comma separated): $r\n";

my @list = $agent->list_api_ids();

Formerly was list_of_available_google_api_ids, which will now give a deprecation warning to switch to list_api_ids.

AUTHOR

Veesh Goldman <veesh@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2017-2023 by Veesh Goldman and Others.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004