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.