NAME
WebService::GoogleAPI::Client::Discovery - Google API discovery service
VERSION
version 0.15
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
* deal with case of service names - either make it case insensitive or lock in a consistent approach - currently smells like case changes on context * handle 403 ( Daily Limit for Unauthenticated Use Exceeded.) errors when reqeusting a disdovery resource for a resvice but do we have access to authenticated reqeusts? * consider refactoring this entire module into UserAgent .. NB - this is also included as property of Services.pm which is the factory for dynamic classes
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' );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 versionSEE 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
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'); # 0NB - 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 arrayreflatest_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
$self->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')TODO: consider ? refactor to allow parameters either as a single api id such as 'gmail' as well as the currently accepted hash keyed on the api and version
SEE ALSO: The following methods are delegated through to Client::Discovery - see perldoc WebService::Client::Discovery for detils
get_method_meta
discover_all
extract_method_discovery_detail_from_api_spec
get_api_discovery_for_api_idlist_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.
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