NAME

Amazon::API

SYNOPSIS

 package Amazon::CloudWatchEvents;

 use parent qw/Amazon::API/;

 @API_METHODS = qw/
                  DeleteRule
                  DescribeEventBus
                  DescribeRule
                  DisableRule
                  EnableRule
                  ListRuleNamesByTarget
                  ListRules
                  ListTargetsByRule
                  PutEvents
                  PutPermission
                  PutRule
                  PutTargets
                  RemovePermission
                  RemoveTargets
                  TestEventPattern/;

 sub new {
   my $class = shift;
   my $options = shift || {};
 
   $class->SUPER::new({
                      %$options,
                      service_url_base => 'events',
                      version          => undef,
                      api              => 'AWSEvents',
                      api_methods      => \@API_METHODS,
                      content_type     => 'application/x-amz-json-1.1'
                     });
 }

 1;

DESCRIPTION

Class to use for constructing AWS API interfaces. Typically used as the parent class, but can be used directly. See Amazon::CloudWatchEvents for an example or sub-classing. See "IMPLEMENTATION NOTES" for using Amazon::API directly to call AWS services.

ERRORS

Errors encountered are returned as an Amazon::API::Error exception object. See Amazon::API::Error/

METHODS

new

 new( options )

credentials

Amazon::Credentials object or at least an object that -can(get_aws_access_key_id)> and -can(get_aws_secret_access_key)> and -can(get_token)>

user_agent

Your own user agent object or by default LWP::UserAgent. Using Furl, if you have it avaiable may result in faster response.

api

The name of the AWS service. Example: AWSEvents

url

The service url. Example: https://events.us-east-1.amazonaws.com

debug

0/1 - will dump request/response if set to true.

action

The API method. Example: PutEvents

content_type

Default content for references passed to the invoke_api() method. The default is application/x-amz-json-1.1.

protocol

One of 'http' or 'https'. Some Amazon services do not support https (yet).

invoke_api

 invoke_api(action, [parameters, [content-type]]);

action

parameters

Parameters to send to the API. Can be a scalar, a hash reference or an array reference.

content-type

If you send the content-type, it is assumed that the parameters are the payload to be sent in the request. Otherwise, the parameters will be converted to a JSON string if the parameters value is a hash reference or a query string if the parameters value is an array reference.

Hence, to send a query string, you should send an array key/value pairs, or an array of scalars of the form Name=Value.

 [ { Action => 'DescribeInstances' } ]
 [ "Action=DescribeInstances" ]

...are both equivalent ways to force the method to send a query string.

decode_response

Attempts to decode the response from the API based on the Content-Type returned in the response header. If there is no Content-Type, then the raw content is returned.

submit

 submit( options )

options is hash of options:

content

Payload to send.

content_type

Content types we have seen used to send values to AWS APIs:

 application/json
 application/x-amz-json-1.0
 application/x-amz-json-1.1
 application/x-www-form-urlencoded

IMPLEMENTATION NOTES

X-Amz-Target

Most of the newer AWS APIs accept a header (X-Amz-Target) in lieu of the CGI parameter Action. Some APIs also want the version in the target, some don't. Sparse documentation about some of the nuances of using the REST interface directly to call AWS APIs.

We use the api value as a trigger to indicate we need to set the Action in the X-Amz-Target header. We also check to see if the version needs to be attached to the Action value as required by some APIs.

  if ( $self->get_api ) {
    if ( $self->get_version) {
      $self->set_target(sprintf("%s_%s.%s", $self->get_api, $self->get_version, $self->get_action));
    }
    else {
      $self->set_target(sprintf("%s.%s", $self->get_api, $self->get_action));
    }

    $request->header('X-Amz-Target', $self->get_target());
  }

DynamoDB & KMS seems to be able to use this in lieu of query variables Action & Version, although again, there seems to be a lot of inconsisitency in the APIs. DynamoDB uses DynamoDB_YYYYMMDD.Action while KMS will not take the version that way and prefers TrentService.Action (with no version). There is no explanation in any of the documentations I have been able to find as to what "TrentService" might actually mean.

In general, the AWS API ecosystem is very organic. Each service seems to have its own rules and protocol regarding what the content of the headers should be. This generic API interface tries to make it possible to use a central class (Amazon::API) as a sort of gateway to the APIs. The most generic interface is simply sending query variables and not much else in the header. APIs like EC2 conform to the that school, so as indicated above we use action to determine whether to send the API action in the header or to assume that it is being sent as one of the query variables.

Rolling a new API

The class will stub out methods for the API if you pass an array of API method names. The stub is equivalent to:

 sub some_api {
   my $self = shift;

   $self ->invoke_api('SomeApi', @_);
 }

Some will also be happy to know that the class will create an equivalent CamelCase version of the method. If you choose to override the method, you should override the snake case version of the method.

As an example, here is a possible implementation of Amazon::CloudWatchEvents that implements one of the API calls.

 package Amazon::CloudWatchEvents;

 use parent qw/Amazon::API/;
 
 sub new {
   my $class = shift;
   my $options = shift || {};

   $options->{api} 'AWSEvents';
   $options->{url} 'https://events.us-east-1.amazonaws.com';
   $options->{api_methods} => [ 'ListRules' ];

   return $class->SUPER::new($options);
 }

 1;

Then...

  my $cwe = new Amazon::CloudWatchEvents();
  $cwe->ListRules({});

Of course, creating a class for the service is optional. It may be desirable however to create higher level and more convenient methods that aid the developer in utilizing a particular API.

 my $api = new Amazon::API({ credentials => new Amazon::Credentials, api => 'AWSEvents', url => 'https://events.us-east-1.amazonaws.com' });
 $api->invoke_api('ListRules', {});

Content-Type

Yet another piece of evidence that suggests the organic nature of the Amazon API ecosystem is their use of multiple forms of input to their methods indicated by the required Content-Type for different services. Some of the variations include:

 application/json
 application/x-amz-json-1.0
 application/x-amz-json-1.1
 application/x-www-form-urlencoded

Accordingly, the invoke_api() can be passed the Content-Type or will try to make "best guess" based on the input parameter you passed. It guesses using the following decision tree:

• If the Content-Type parameter is passed as the third argument, that is used. Full stop.

• If the parameters value to invoke_api() is a reference, then the Content-Type is either the value of get_content_type or application/x-amzn-json-1.1.

• If the parameters value to invoke_api() is a scalar, then the Content-Type is application/x-www-form-urlencoded.

You can set the default Content-Type used for the calling service when a reference is passed to the invoke_api() method by passing the content_type option to the constructor.

 $class->SUPER::new({%@_, content_type => 'application/x-amz-json-1.1', api => 'AWSEvents', 
                     url => 'https://events.us-east-1.amazonaws.com'});

SEE OTHER

Amazon::Credentials, Amazon::API::Error

AUTHOR

Rob Lauer - <rlauer6@comcast.net>

cpanm Amazon::API

perl -MCPAN -e shell
install Amazon::API