WebService::CRUST - A lightweight Client for making REST calls
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 $w->get($url, appid => 'YahooDemo')->Timestamp;
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'
);
for (@{$result->Items->Item}) {
printf "%s - %s\n",
$_->ASIN,
$_->ItemAttributes->Title;
}
my $w = new WebService::CRUST( <options> );
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
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');
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
Number of seconds to wait for a request to return. Default is LWP's default (180 seconds).
Pass an LWP::UserAgent object that you want to use instead of the default.
What format to use. Defaults to XML::Simple. To use something like JSON or JSON::XS:
my $w1 = new WebService::CRUST(format => [ 'JSON', 'objToJson', 'jsonToObj' ]); my $w2 = new WebService::CRUST(format => [ 'JSON::XS', 'decode', 'encode', 'decode' ]); $w1->get($url); $w2->get($url);
The second and third arguments are the methods to serialize or deserialize. Either one 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.
The HTTP_BASIC username to send for authentication
The HTTP_BASIC password to send for authentication
my $w = new WebService::CRUST(
basic_username => 'user',
basic_password => 'pass'
);
$w->get('http://something/');
A hashref of alternate options to pass the data formatter.
Turn debugging on or off.
Performs a GET request with the specified options. Returns a WebService::CRUST::Result object on success or undef on failure.
Performs a HEAD request with the specified options. Returns a WebService::CRUST::Result object on success or undef on failure.
Performs a PUT request with the specified options. Returns a WebService::CRUST::Result object on success or 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 });
If that content is a reference to a hash or array, it will be serialized using the formatter specified.
Performs a POST request with the specified options. Returns a WebService::CRUST::Result object on success or undef on failure.
Same as get/post except the first argument is the method to use.
my $w = new WebService::CRUST; $w->request( 'HEAD', $url );
Returns a WebService::CRUST::Result object on success or undef on failure.
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;
Get or set the LWP::UserAgent object.
Mostly internal method for debugging. Prints a message to STDERR by default.
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 "xlink:href", we will auto inflate that to another URL. See WebService::CRUST::Result for more.
Results from a request come back as an WebService::CRUST::Result object. If you want to look at what came back (so you know what methods to request), just dump the result's ->request accessor:
my $w = new WebService::CRUST(base => 'http://something/'); my $result = $w->method; # What does my result contain? print Dumper $result->result; # Returns: { attr => 'value' } # Ah... my result has an attribute called 'attr' $result->attr; # 'value'
Changes in 0.3 and 0.4 broke compatibility with previous releases (where you could just access the result as a hash directly). If you had code that looked like this:
my $x = $crust->foo;
$x->{attr};
You'll need to change it to one of these:
$x->result->{attr};
$x->attr;
WebService::CRUST::Result, Catalyst::Model::WebService::CRUST, LWP, XML::Simple
Chris Heschong <chris@wiw.org>
