The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WebService-GoogleAPI-Client-0.27
River stage zero No dependents
2 ++
/ 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