The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WebService-GoogleAPI-Client-0.12
River stage zero No dependents
2 ++
/ WebService::GoogleAPI::Client::Discovery

NAME

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

VERSION

version 0.12

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 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

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

$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_id

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.

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