# REST::Consumer
A general-purpose client for interacting with RESTful HTTP services
### Synopsis
This module provides an interface that encapsulates building an http request, sending, and parsing responses. It also retries on failed requests and has configurable timeouts.
### Usage
First configure the REST::Consumer class. This only needs to be done once per process and the results will be cached in a file. You can then refer to the service by name.
REST::Consumer->configure('
http://somewhere.com/consumer/config');
And / or:
REST::Consumer->configure({
'google-calendar' => {
url => '
https://apps-apis.google.com',
},
'google-accounts' => {
url => '
https://accounts.google.com',
},
});
Then later:
my $media = REST::Consumer->service('google-calendar')->get(
path => '/users/me/calendarList',
timeout => 5,
retry => 5,
);
use Data::Dumper;
print Dumper($media);
Example Using Authentication:
my $client = REST::Consumer->new(
host => 'service.shuttercorp.net',
auth => {
type => 'basic',
username => 'mrbigglesworth',
password => 'cupcake',
}
)
$client->get(
path => ....
params => {...}
)
Example Using Handlers:
my $result = $client->post(
path => '/foo',
...
handlers => {
409 => sub {
my ($h) = @_;
if ($h->response_parseable) {
my $conflicting_user = $h->parsed_response->{user};
# ->parsed_response will raise an error if the response
# is not in fact the sort of thing that could be parsed
# (e.g. a flat string)
return "conflict with $conflicting_user";
}
return $h->default;
# resume normal flow (retries, etc)
},
420 => sub {
# Twitter's custom 'enhance your calm' rate limit
my ($h) = @_;
# (assuming your code has a $self->logger capability)
$self->logger->warn("service is rate-limiting us with drug references");
return $h->retry; # explicit retry is also available (respects retry limit)
},
4xx => sub {
my ($h) = @_;
# (assuming your code has a $self->logger capability)
$self->logger->critical("Bad request! Response body: %s", $h->response_body);
die "IncompetentProgrammerException";
},
}
);
# $result contains the parsed response, or the string "conflict with <user>",
# or it dies with an IncompetentProgrammerException.
