NAME

WWW::GCloud - Core of Google Cloud REST API framework

SYNOPSIS

use v6.e.PREVIEW;
use WWW::GCloud;
use WWW::GCloud::API::ResourceMgr;

my $gcloud = WWW::GCloud.new;

say "Available projects:";
react whenever $gcloud.resource-manager.projects.list -> $project {
    say "  * ", $project.project-id;
}

my $new-project-id = "my-unique-project-name";
await $gcloud.resource-manager.projects.create(
    $gcloud.resource-manager.new-project(
        "This is project description",
        id => $new-project-id,
        labels => { :label1('label_value'), :label2("another_value") } );
).andthen({
    say .result; # Would dump an instance of WWW::GCloud::R::Operation
})
.orelse({
    # Choose how to react to an error
    note "Can't create a new project '$new-project-id'";
    .cause.rethrow
});

DESCRIPTION

This is going to be my worst documentation so far! I apologize for this, but simply unable to write it yet. Will provide a few important notes though.

So far, best way to start with this module is to explore examples/ and t/ directories. Apparently, inspecting the sources in lib/ would be the most helpful!

WWW::GCloud Object Structure

Google Cloud structures its API into themed APIs like Resource Manager, Storage, Vision, etc. Each particular API, in turns, provides resources where methods belong. WWW::GCloud tries to follow the same pattern. Say, in the SYNOPSIS $gcloud.resource-manager is WWW::GCloud::API::ResourceMgr instance implementing Resource Manager API. Then, $gcloud.resource-manager.projects is the implementation of projects resource.

Framework Namespacing

The framework is extensible. WWW::GCloud class by itself implements no APIs. New ones can be implemented any time. Basically, starting a new API module is as simple as doiing:

use v6.e.PREVIEW;
unit class WWW::GCloud::API::NewOne;

use WWW::GCloud::API;

also does WWW::GCloud::API['new-one'];

has $.base-url = 'https://storage.googleapis.com/newone/v1';

Now, with `use WWW::GCloud::API::NewOne;` a method new-one becomes automatically available with any instance of WWW::GCloud.

As you can see, WWW::GCloud::API:: namespace is used. Here is the list of standard namespaces:

• WWW::GCloud::API::

  Apparently, any new API implementation must reside within this one.

• WWW::GCloud::R::

  This is where record types are to be declared. For example, WWW::GCloud::R::Operation represents an Operation.

  The R:: namespace itself is better be reserved for commonly used types of records. For an API-specific record it is recommended to use their own sub-spaces. WWW::GCloud::API::Storage is using WWW::GCloud::R::Storage::, for example.

• WWW::GCloud::RR::

  RR stands for Record Roles. This is where roles, used by record classes, are to be located. Same API sub-naming rule applies.

Type Mapping

Sometimes it is useful to map a core class into a user's child class. For example, an output from text recognition APIs could be "patched" so that records using vertexes (like actual symbols detected) can be represented with user classes where user's own coordinate system is used. So, that instead of re-building our class based on what's returned by the API we can use lazy approaches to simply construct the parts we need:

use AttrX::Mooish;
class MyBoundingPoly is gc-wrap(WWW::GCloud::R::Vision::BoundingPoly) {
    has MyRect:D @.bounding-path;

    method build-bounding-path {
        self.vertices.map: { self.covert-point($^vertex) }
    }
}

See examples/basic-usage.raku and t/050-type-map.rakutest.

A Couple Of Recommendations

Consider using traits for declarations. For example, a new record class is best declared as:

use v6.e.PREVIEW;
unit class WWW::GCloud::R::NewAapi::ARec;

use WWW::GCloud::Record;

also is gc-record;

has Str $.someField;
has Int $.aCounter;

The trait would automatically mark all record attributes (except where explicit `is json-skip` is applied) as JSON-serializable as if `is json` has been applied to them manually.

Other useful traits are:

• gc-wrap from WWW::GCloud::Record

• gc-params from WWW::GCloud::QueryParams (find its usages in API modules and see t/040-query-params.rakutest)

• does when used with WWW::GCloud::API automates registering of an API module with WWW::GCloud

COPYRIGHT

(c) 2023, Vadim Belman <[email protected]>

LICENSE

Artistic License 2.0

See the LICENSE|../../../../LICENSE file in this distribution.