view release on metacpan or  search on metacpan

lib/Amazon/API.pm  view on Meta::CPAN

		  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;

=head1 DESCRIPTION

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

=head1 ERRORS

Errors encountered are returned as an C<Amazon::API::Error> exception
object.  See L<Amazon::API::Error>/

=cut

use strict;
use warnings;

use parent qw/Class::Accessor Exporter/;

use Amazon::API::Error;
use Amazon::Credentials;

use AWS::Signature4;
use Data::Dumper;
use HTTP::Request;
use JSON qw/to_json from_json/;
use LWP::UserAgent;
use Scalar::Util qw/reftype/;
use XML::Simple;

__PACKAGE__->follow_best_practice;

__PACKAGE__->mk_accessors(qw/action api api_methods version content_type
			     http_method credentials response protocol
			     region url service_url_base 
			     signer target user_agent debug last_action
			     aws_access_key_id aws_secret_access_key token
			    /);

use vars qw/@EXPORT $VERSION/;

@EXPORT=qw/$VERSION/;

our $VERSION = '1.1.4-1'; $VERSION=~s/\-.*$//;

=pod

=head1 METHODS

=head2 new

 new( options )

=over 5

=item credentials (required)

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

=item user_agent

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

=item api (reqired)

The name of the AWS service.  Example: AWSEvents

=item url

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

=item debug

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

=item action

The API method. Example: PutEvents

=item content_type

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

=item protocol

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

=back

=cut

sub new {
  my $class = shift;
  my $self = $class->SUPER::new(@_);

  unless ($self->get_user_agent) {
    $self->set_user_agent(new LWP::UserAgent);
  }

  # some APIs are GET only (I'm talkin' to you IAM!)
  $self->set_http_method('POST')
    unless defined $self->get_http_method;
  
  # note some APIs are global, hence an API may send '' to indicate global
  $self->set_region('us-east-1')
    unless defined $self->get_region;
  
  unless ( $self->get_credentials ) {
    $self->set_credentials( new Amazon::Credentials( { aws_secret_access_key => $self->get_aws_secret_access_key,
						       aws_access_key_id     => $self->get_aws_access_key_id,
						       token                 => $self->get_token
						     })
			  );
  }

  $self->set_protocol('https')
    unless $self->get_protocol();
  
  unless ( $self->get_url ) {
    if ( $self->get_service_url_base() ) {
      if ( $self->get_region ) {
	$self->set_url(sprintf("%s://%s.%s.amazonaws.com", $self->get_protocol, $self->get_service_url_base, $self->get_region));
      }
      else {
	$self->set_url(sprintf("%s://%s.amazonaws.com", $self->get_protocol, $self->get_service_url_base));
      }
    }
    else {
      die "ERROR: no url or service_url defined.\n"
    }
  }
  
  $self->set_signer(AWS::Signature4->new(-access_key => $self->get_credentials->get_aws_access_key_id,
					 -secret_key => $self->get_credentials->get_aws_secret_access_key)
		   );
 
  
  if ( $self->get_api_methods ) {
    no strict 'refs';
    no warnings 'redefine';
    
    foreach my $api (@{$self->get_api_methods}) {
      my $method = lcfirst $api;
      
      $method =~s/([a-z])([A-Z])/$1_$2/g;
      $method = lc $method;
      
      # snake case rules the day
      *{"Amazon::API::" . $method} = sub { shift->invoke_api("$api", @_) };
      # but some prefer camels
      *{"Amazon::API::" . $api} = sub { shift->$method(@_) }; # pass on to the snake
    }
  }
  
  $self->set_content_type('application/x-amz-json-1.1') unless
    $self->get_content_type;
  
  $self;
}

sub get_api_name {
  my $self = shift;
  
  return join("", map { ucfirst } split /_/, shift);
}

=pod

=head2 invoke_api

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

=over 5

=item action

=item parameters

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

=item content-type

If you send the C<content-type>, it is assumed that the parameters are
the payload to be sent in the request.  Otherwise, the C<parameters>
will be converted to a JSON string if the C<parameters> value is a
hash reference or a query string if the C<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" ]