NAME

WWW::SwaggerClient::Role - a Moose role for the Estuary API

This is the API for the Estuary application.

VERSION

Automatically generated by the Swagger Codegen project:

• API version: 0.0.0
• Package version: 1.0.0
• Build package: io.swagger.codegen.languages.PerlClientCodegen For more information, please visit https://docs.estuary.tech/feedback

A note on Moose

This role is the only component of the library that uses Moose. See WWW::SwaggerClient::ApiFactory for non-Moosey usage.

SYNOPSIS

The Perl Swagger Codegen project builds a library of Perl modules to interact with a web service defined by a OpenAPI Specification. See below for how to build the library.

This module provides an interface to the generated library. All the classes, objects, and methods (well, not quite *all*, see below) are flattened into this role.

    package MyApp;
    use Moose;
    with 'WWW::SwaggerClient::Role';

    package main;

    my $api = MyApp->new({ tokens => $tokens });

    my $pet = $api->get_pet_by_id(pet_id => $pet_id);

Structure of the library

The library consists of a set of API classes, one for each endpoint. These APIs implement the method calls available on each endpoint.

Additionally, there is a set of "object" classes, which represent the objects returned by and sent to the methods on the endpoints.

An API factory class is provided, which builds instances of each endpoint API.

This Moose role flattens all the methods from the endpoint APIs onto the consuming class. It also provides methods to retrieve the endpoint API objects, and the API factory object, should you need it.

For documentation of all these methods, see AUTOMATIC DOCUMENTATION below.

Configuring authentication

In the normal case, the OpenAPI Spec will describe what parameters are required and where to put them. You just need to supply the tokens.

my $tokens = {
    # basic
    username => $username,
    password => $password,

    # oauth
    access_token => $oauth_token,

    # keys
    $some_key => { token => $token,
                   prefix => $prefix,
                   in => $in,             # 'head||query',
                   },

    $another => { token => $token,
                  prefix => $prefix,
                  in => $in,              # 'head||query',
                  },
    ...,

    };

    my $api = MyApp->new({ tokens => $tokens });

Note these are all optional, as are prefix and in, and depend on the API you are accessing. Usually prefix and in will be determined by the code generator from the spec and you will not need to set them at run time. If not, in will default to 'head' and prefix to the empty string.

The tokens will be placed in a L<WWW::SwaggerClient::Configuration> instance as follows, but you don't need to know about this.

• $cfg->{username}

  String. The username for basic auth.

• $cfg->{password}

  String. The password for basic auth.

• $cfg->{api_key}

  Hashref. Keyed on the name of each key (there can be multiple tokens).

        $cfg->{api_key} = {
                secretKey => 'aaaabbbbccccdddd',
                anotherKey => '1111222233334444',
                };

• $cfg->{api_key_prefix}

  Hashref. Keyed on the name of each key (there can be multiple tokens). Note not all api keys require a prefix.

        $cfg->{api_key_prefix} = {
                secretKey => 'string',
                anotherKey => 'same or some other string',
                };

• $cfg->{access_token}

  String. The OAuth access token.

METHODS

base_url

The generated code has the base_url already set as a default value. This method returns the current value of base_url.

api_factory

Returns an API factory object. You probably won't need to call this directly.

    $self->api_factory('Pet'); # returns a WWW::SwaggerClient::PetApi instance

    $self->pet_api;            # the same

MISSING METHODS

Most of the methods on the API are delegated to individual endpoint API objects (e.g. Pet API, Store API, User API etc). Where different endpoint APIs use the same method name (e.g. new()), these methods can't be delegated. So you need to call $api->pet_api->new().

In principle, every API is susceptible to the presence of a few, random, undelegatable method names. In practice, because of the way method names are constructed, it's unlikely in general that any methods will be undelegatable, except for:

    new()
    class_documentation()
    method_documentation()

To call these methods, you need to get a handle on the relevant object, either by calling $api->foo_api or by retrieving an object, e.g. $api->get_pet_by_id(pet_id => $pet_id). They are class methods, so you could also call them on class names.

BUILDING YOUR LIBRARY

See the homepage https://github.com/swagger-api/swagger-codegen for full details. But briefly, clone the git repository, build the codegen codebase, set up your build config file, then run the API build script. You will need git, Java 7 or 8 and Apache maven 3.0.3 or better already installed.

The config file should specify the project name for the generated library:

    {"moduleName":"WWW::MyProjectName"}

Your library files will be built under WWW::MyProjectName.

      $ git clone https://github.com/swagger-api/swagger-codegen.git
      $ cd swagger-codegen
      $ mvn package
      $ java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
-i [URL or file path to JSON swagger API spec] \
-l perl \
-c /path/to/config/file.json \
-o /path/to/output/folder

Bang, all done. Run the autodoc script in the bin directory to see the API you just built.

AUTOMATIC DOCUMENTATION

You can print out a summary of the generated API by running the included autodoc script in the bin directory of your generated library. A few output formats are supported:

      Usage: autodoc [OPTION]

-w           wide format (default)
-n           narrow format
-p           POD format
-H           HTML format
-m           Markdown format
-h           print this help message
-c           your application class

The -c option allows you to load and inspect your own application. A dummy namespace is used if you don't supply your own class.

DOCUMENTATION FROM THE OpenAPI Spec

Additional documentation for each class and method may be provided by the Swagger spec. If so, this is available via the class_documentation() and method_documentation() methods on each generated object class, and the method_documentation() method on the endpoint API classes:

    my $cmdoc = $api->pet_api->method_documentation->{$method_name};

    my $odoc = $api->get_pet_by_id->(pet_id => $pet_id)->class_documentation;
    my $omdoc = $api->get_pet_by_id->(pet_id => $pet_id)->method_documentation->{method_name};

Each of these calls returns a hashref with various useful pieces of information.

LOAD THE MODULES

To load the API packages:

use WWW::SwaggerClient::AdminApi;
use WWW::SwaggerClient::AutoretrieveApi;
use WWW::SwaggerClient::CollectionsApi;
use WWW::SwaggerClient::ContentApi;
use WWW::SwaggerClient::DealsApi;
use WWW::SwaggerClient::DefaultApi;
use WWW::SwaggerClient::MetricsApi;
use WWW::SwaggerClient::MinerApi;
use WWW::SwaggerClient::NetApi;
use WWW::SwaggerClient::PeeringApi;
use WWW::SwaggerClient::PeersApi;
use WWW::SwaggerClient::PinningApi;
use WWW::SwaggerClient::PublicApi;
use WWW::SwaggerClient::UserApi;

To load the models:

use WWW::SwaggerClient::Object::CollectionsCollection;
use WWW::SwaggerClient::Object::MainCreateCollectionBody;
use WWW::SwaggerClient::Object::MainDeleteContentFromCollectionBody;
use WWW::SwaggerClient::Object::MainEstimateDealBody;
use WWW::SwaggerClient::Object::MainGetApiKeysResp;
use WWW::SwaggerClient::Object::MainImportDealBody;
use WWW::SwaggerClient::Object::MainUserStatsResponse;
use WWW::SwaggerClient::Object::UtilContentAddIpfsBody;
use WWW::SwaggerClient::Object::UtilContentAddResponse;
use WWW::SwaggerClient::Object::UtilContentCreateBody;
use WWW::SwaggerClient::Object::UtilHttpError;

GETTING STARTED

Put the Perl SDK under the 'lib' folder in your project directory, then run the following

#!/usr/bin/perl
use lib 'lib';
use strict;
use warnings;
# load the API package
use WWW::SwaggerClient::AdminApi;
use WWW::SwaggerClient::AutoretrieveApi;
use WWW::SwaggerClient::CollectionsApi;
use WWW::SwaggerClient::ContentApi;
use WWW::SwaggerClient::DealsApi;
use WWW::SwaggerClient::DefaultApi;
use WWW::SwaggerClient::MetricsApi;
use WWW::SwaggerClient::MinerApi;
use WWW::SwaggerClient::NetApi;
use WWW::SwaggerClient::PeeringApi;
use WWW::SwaggerClient::PeersApi;
use WWW::SwaggerClient::PinningApi;
use WWW::SwaggerClient::PublicApi;
use WWW::SwaggerClient::UserApi;

# load the models
use WWW::SwaggerClient::Object::CollectionsCollection;
use WWW::SwaggerClient::Object::MainCreateCollectionBody;
use WWW::SwaggerClient::Object::MainDeleteContentFromCollectionBody;
use WWW::SwaggerClient::Object::MainEstimateDealBody;
use WWW::SwaggerClient::Object::MainGetApiKeysResp;
use WWW::SwaggerClient::Object::MainImportDealBody;
use WWW::SwaggerClient::Object::MainUserStatsResponse;
use WWW::SwaggerClient::Object::UtilContentAddIpfsBody;
use WWW::SwaggerClient::Object::UtilContentAddResponse;
use WWW::SwaggerClient::Object::UtilContentCreateBody;
use WWW::SwaggerClient::Object::UtilHttpError;

# for displaying the API response data
use Data::Dumper;
use WWW::SwaggerClient::;

my $api_instance = WWW::SwaggerClient::->new(

    # Configure API key authorization: bearerAuth
    api_key => {'Authorization' => 'YOUR_API_KEY'},
    # uncomment below to setup prefix (e.g. Bearer) for API key, if needed
    #api_key_prefix => {'Authorization' => 'Bearer'},
);

my $body = [WWW::SwaggerClient::Object::ARRAY[string]->new()]; # ARRAY[string] | Peer ids

eval {
    $api_instance->admin_peering_peers_delete(body => $body);
};
if ($@) {
    warn "Exception when calling AdminApi->admin_peering_peers_delete: $@\n";
}

DOCUMENTATION FOR API ENDPOINTS

All URIs are relative to https://api.estuary.tech

Class	Method	HTTP request	Description
AdminApi	admin_peering_peers_delete	DELETE /admin/peering/peers	Remove peers on Peering Service
AdminApi	admin_peering_peers_get	GET /admin/peering/peers	List all Peering peers
AdminApi	admin_peering_peers_post	POST /admin/peering/peers	Add peers on Peering Service
AdminApi	admin_peering_start_post	POST /admin/peering/start	Start Peering
AdminApi	admin_peering_status_get	GET /admin/peering/status	Check Peering Status
AdminApi	admin_peering_stop_post	POST /admin/peering/stop	Stop Peering
AdminApi	admin_system_config_get	GET /admin/system/config	Get systems(estuary/shuttle) config
AdminApi	admin_users_get	GET /admin/users	Get all users
AutoretrieveApi	admin_autoretrieve_init_post	POST /admin/autoretrieve/init	Register autoretrieve server
AutoretrieveApi	admin_autoretrieve_list_get	GET /admin/autoretrieve/list	List autoretrieve servers
AutoretrieveApi	autoretrieve_heartbeat_post	POST /autoretrieve/heartbeat	Marks autoretrieve server as up
CollectionsApi	collections_coluuid_commit_post	POST /collections/{coluuid}/commit	Produce a CID of the collection contents
CollectionsApi	collections_coluuid_contents_delete	DELETE /collections/{coluuid}/contents	Deletes a content from a collection
CollectionsApi	collections_coluuid_delete	DELETE /collections/{coluuid}	Deletes a collection
CollectionsApi	collections_coluuid_get	GET /collections/{coluuid}	Get contents in a collection
CollectionsApi	collections_coluuid_post	POST /collections/{coluuid}	Add contents to a collection
CollectionsApi	collections_fs_add_post	POST /collections/fs/add	Add a file to a collection
CollectionsApi	collections_get	GET /collections/	List all collections
CollectionsApi	collections_post	POST /collections/	Create a new collection
ContentApi	content_add_car_post	POST /content/add-car	Add Car object
ContentApi	content_add_ipfs_post	POST /content/add-ipfs	Add IPFS object
ContentApi	content_add_post	POST /content/add	Add new content
ContentApi	content_aggregated_content_get	GET /content/aggregated/{content}	Get aggregated content stats
ContentApi	content_all_deals_get	GET /content/all-deals	Get all deals for a user
ContentApi	content_bw_usage_content_get	GET /content/bw-usage/{content}	Get content bandwidth
ContentApi	content_create_post	POST /content/create	Add a new content
ContentApi	content_deals_get	GET /content/deals	Content with deals
ContentApi	content_ensure_replication_datacid_get	GET /content/ensure-replication/{datacid}	Ensure Replication
ContentApi	content_failures_content_get	GET /content/failures/{content}	List all failures for a content
ContentApi	content_id_get	GET /content/{id}	Content
ContentApi	content_importdeal_post	POST /content/importdeal	Import a deal
ContentApi	content_list_get	GET /content/list	List all pinned content
ContentApi	content_read_cont_get	GET /content/read/{cont}	Read content
ContentApi	content_staging_zones_get	GET /content/staging-zones	Get staging zone for user
ContentApi	content_stats_get	GET /content/stats	Get content statistics
ContentApi	content_status_id_get	GET /content/status/{id}	Content Status
DealsApi	deal_estimate_post	POST /deal/estimate	Estimate the cost of a deal
DealsApi	deal_info_dealid_get	GET /deal/info/{dealid}	Get Deal Info
DealsApi	deal_proposal_propcid_get	GET /deal/proposal/{propcid}	Get Proposal
DealsApi	deal_query_miner_get	GET /deal/query/{miner}	Query Ask
DealsApi	deal_status_by_proposal_propcid_get	GET /deal/status-by-proposal/{propcid}	Get Deal Status by PropCid
DealsApi	deal_status_miner_propcid_get	GET /deal/status/{miner}/{propcid}	Deal Status
DealsApi	deal_transfer_in_progress_get	GET /deal/transfer/in-progress	Transfer In Progress
DealsApi	deals_failures_get	GET /deals/failures	Get storage failures for user
DealsApi	deals_make_miner_post	POST /deals/make/{miner}	Make Deal
DealsApi	deals_status_deal_get	GET /deals/status/{deal}	Get Deal Status
DealsApi	public_deals_failures_get	GET /public/deals/failures	Get storage failures
DealsApi	public_miners_storage_query_miner_get	GET /public/miners/storage/query/{miner}	Query Ask
DefaultApi	deal_transfer_status_post	POST /deal/transfer/status
MetricsApi	public_metrics_deals_on_chain_get	GET /public/metrics/deals-on-chain	Get deal metrics
MinerApi	public_miners_deals_miner_get	GET /public/miners/deals/{miner}	Get all miners deals
MinerApi	public_miners_stats_miner_get	GET /public/miners/stats/{miner}	Get miner stats
NetApi	net_addrs_get	GET /net/addrs	Net Addrs
NetApi	public_miners_failures_miner_get	GET /public/miners/failures/{miner}	Get all miners
NetApi	public_miners_get	GET /public/miners	Get all miners
NetApi	public_net_addrs_get	GET /public/net/addrs	Net Addrs
NetApi	public_net_peers_get	GET /public/net/peers	Net Peers
PeeringApi	admin_peering_peers_delete	DELETE /admin/peering/peers	Remove peers on Peering Service
PeeringApi	admin_peering_peers_get	GET /admin/peering/peers	List all Peering peers
PeeringApi	admin_peering_peers_post	POST /admin/peering/peers	Add peers on Peering Service
PeeringApi	admin_peering_start_post	POST /admin/peering/start	Start Peering
PeeringApi	admin_peering_status_get	GET /admin/peering/status	Check Peering Status
PeeringApi	admin_peering_stop_post	POST /admin/peering/stop	Stop Peering
PeersApi	admin_peering_peers_delete	DELETE /admin/peering/peers	Remove peers on Peering Service
PeersApi	admin_peering_peers_get	GET /admin/peering/peers	List all Peering peers
PeersApi	admin_peering_peers_post	POST /admin/peering/peers	Add peers on Peering Service
PeersApi	admin_peering_start_post	POST /admin/peering/start	Start Peering
PeersApi	admin_peering_status_get	GET /admin/peering/status	Check Peering Status
PeersApi	admin_peering_stop_post	POST /admin/peering/stop	Stop Peering
PinningApi	pinning_pins_get	GET /pinning/pins	List all pin status objects
PinningApi	pinning_pins_pinid_delete	DELETE /pinning/pins/{pinid}	Delete a pinned object
PinningApi	pinning_pins_pinid_get	GET /pinning/pins/{pinid}	Get a pin status object
PinningApi	pinning_pins_pinid_post	POST /pinning/pins/{pinid}	Replace a pinned object
PinningApi	pinning_pins_post	POST /pinning/pins	Add and pin object
PublicApi	public_by_cid_cid_get	GET /public/by-cid/{cid}	Get Content by Cid
PublicApi	public_info_get	GET /public/info	Get public node info
PublicApi	public_metrics_deals_on_chain_get	GET /public/metrics/deals-on-chain	Get deal metrics
PublicApi	public_miners_deals_miner_get	GET /public/miners/deals/{miner}	Get all miners deals
PublicApi	public_miners_failures_miner_get	GET /public/miners/failures/{miner}	Get all miners
PublicApi	public_miners_get	GET /public/miners	Get all miners
PublicApi	public_miners_stats_miner_get	GET /public/miners/stats/{miner}	Get miner stats
PublicApi	public_net_addrs_get	GET /public/net/addrs	Net Addrs
PublicApi	public_net_peers_get	GET /public/net/peers	Net Peers
PublicApi	public_stats_get	GET /public/stats	Public stats
UserApi	user_api_keys_get	GET /user/api-keys	Get API keys for a user
UserApi	user_api_keys_key_delete	DELETE /user/api-keys/{key}	Revoke a User API Key.
UserApi	user_api_keys_post	POST /user/api-keys	Create API keys for a user
UserApi	user_export_get	GET /user/export	Export user data
UserApi	user_stats_get	GET /user/stats	Create API keys for a user

DOCUMENTATION FOR MODELS

• WWW::SwaggerClient::Object::CollectionsCollection
• WWW::SwaggerClient::Object::MainCreateCollectionBody
• WWW::SwaggerClient::Object::MainDeleteContentFromCollectionBody
• WWW::SwaggerClient::Object::MainEstimateDealBody
• WWW::SwaggerClient::Object::MainGetApiKeysResp
• WWW::SwaggerClient::Object::MainImportDealBody
• WWW::SwaggerClient::Object::MainUserStatsResponse
• WWW::SwaggerClient::Object::UtilContentAddIpfsBody
• WWW::SwaggerClient::Object::UtilContentAddResponse
• WWW::SwaggerClient::Object::UtilContentCreateBody
• WWW::SwaggerClient::Object::UtilHttpError

DOCUMENTATION FOR AUTHORIZATION

bearerAuth

• Type: API key
• API key parameter name: Authorization
• Location: HTTP header