NAME

WebService::CRUST - A lightweight Client for making REST calls

SYNOPSIS

Simple:

  ## Connect to Yahoo's Time service to see what time it is.

  use WebService::CRUST;
  use Data::Dumper;

  my $url = 'http://developer.yahooapis.com/TimeService/V1/getTime';
  my $w = new WebService::CRUST;

  print Dumper $w->get($url, appid => 'YahooDemo');

Slightly more complex example, where we connect to Amazon and get a list of albums by the Magnetic Fields:

  ## Connect to Amazon and get a list of all the albums by the Magnetic Fields

  my $w = new WebService::CRUST(
    base => 'http://webservices.amazon.com/onca/xml?Service=AWSECommerceService',
    request_key => 'Operation',
    params => { AWSAccessKeyId => 'my_amazon_key' }
  );

  my $result = $w->ItemSearch(
    SearchIndex => 'Music',
    Keywords => 'Magnetic Fields'
  )->{Items};

  for (@{$result->{Item}}) {
    printf "%s - %s\n", 
      $_->{ASIN}, 
      $_->{ItemAttributes}->{Title};
  }

CONSTRUCTOR

new

my $w = new WebService::CRUST( <options> );

OPTIONS

base

Sets a base URL to perform actions on. Example:

  my $w = new WebService::CRUST(base => 'http://somehost.com/API/');
  $w->get('foo'); # calls http://somehost.com/API/foo
  $w->foo;        # Same thing but AUTOLOADED

params

Pass hashref of options to be sent with every query. Example:

  my $w = new WebService::CRUST( params => { appid => 'YahooDemo' });
  $w->get('http://developer.yahooapis.com/TimeService/V1/getTime');
  

Or combine with base above to make your life easier:

  my $w = new WebService::CRUST(
    base => 'http://developer.yahooapis.com/TimeService/V1/',
    params => { appid => 'YahooDemo' }
  );
  $w->getTime(format => 'ms');

request_key

Use a specific param argument for the action veing passed, for instance, when talking to Amazon, instead of calling /method you have to call ?Operation=method. Here's some example code:

  my $w = new WebService::CRUST(
    base => 'http://webservices.amazon.com/onca/xml?Service=AWSECommerceService',
    request_key => 'Operation',
    params => { AWSAccessKeyId => 'my_key' }
  );

  $w->ItemLookup(ItemId => 'B00000JY1X');
  # does a GET on http://webservices.amazon.com/onca/xml?Service=AWSECommerceService&Operation=ItemLookup&ItemId=B00000JY1X&AWSAccessKeyId=my_key

timeout

Number of seconds to wait for a request to return. Default is LWP's default (180 seconds).

ua

Pass an LWP::UserAgent object that you want to use instead of the default.

format

What format to use. Defaults to XML::Simple. To use something like JSON:

  my $w = new WebService::CRUST(format => [ 'JSON', 'objToJson' ]);
  $w->get($url);

The second argument can also be a coderef, so for instance:

  my $w = new WebService::CRUST(
      format => [ 'JSON::Syck', sub { JSON::Syck::Load(shift) } ]
  );
  $w->get($url);

Formatter classes are loaded dynamically if needed, so you don't have to 'use' them first.

head2 basic_username

The HTTP_BASIC username to send for authentication

head2 basic_password

The HTTP_BASIC password to send for authentication

  my $w = new WebService::CRUST(
      basic_username => 'user',
      basic_password => 'pass'
  );
  $w->get('http://something/');

opts

A hashref of alternate options to pass the data formatter.

debug

Turn debugging on or off.

METHODS

get

Performs a GET request with the specified options. Returns undef on failure.

head

Performs a HEAD request with the specified options. Returns undef on failure.

put

Performs a PUT request with the specified options. Returns undef on failure.

If -content is passed as a parameter, that will be set as the content of the PUT request:

  $w->put('something', { -content => $content });

post

Performs a POST request with the specified options. Returns undef on failure.

request

Same as get/post except the first argument is the method to use.

  my $w = new WebService::CRUST;
  $w->request( 'HEAD', $url );

Returns undef on failure.

response

The HTTP::Response of the last request.

  $w->get('action');
  $w->response->code eq 200 and print "Success\n";
  
  $w->get('invalid_action') or die $w->response->status_line;

ua

Get or set the LWP::UserAgent object.

debug

Mostly internal method for debugging. Prints a message to STDERR by default.

AUTOLOAD

WebService::CRUST has some AUTOLOAD syntactical sugar, such that the following are equivalent:

  my $w = new WebService::CRUST(base => 'http://something/');

  # GET request examples
  $w->get('foo', key => $val);
  $w->get_foo(key => $val);
  $w->foo(key => $val);

  # POST request examples
  $w->post('foo', key => $val);
  $w->post_foo(key => $val);

The pattern is $obj->(get|head|post|put)_methodname;

Additionally, instead of accessing keys in a hash, you can call them as methods:

   my $response = $w->foo(key => $val);
   
   # These are equivalent
   $response->{bar}->{baz};
   $response->bar->baz;

If an element of your object returns with a key called "CRUST__Result", we will auto inflate to another URL. See WebService::CRUST::Result for more.

SEE ALSO

WebService::CRUST::Result, Catalyst::Model::WebService::CRUST, LWP, XML::Simple

AUTHOR

Chris Heschong <chris@wiw.org>

cpanm WebService::CRUST

perl -MCPAN -e shell
install WebService::CRUST