NAME

MooseX::Role::REST::Consumer

VERSION

version 0.003

SYNOPSIS

package Foo;
use Moose;
with 'MooseX::Role::REST::Consumer' => {
  service_host => 'somewhere.over.the.rainbow',
  resource_path => '/path/to/my/resource/:id',
};

my $object = Foo->get(route_params => {id => 1});

if ($object->is_success) {
 print $object->data->{something_that_came_back};
}

DESCRIPTION

At Shutterstock we love REST and we take it so seriously that we think 
our code should be RESTfully lazy. Now one can have a Moose model
without needing to deal with all the marshalling details.

Schema Definitions/Configuration

When setting up a class the following are the supported
parameters that L<MooseX::Role::REST::Consumer> will support.

For example a typical configuration would looke like the following:

with 'MooseX::Role::REST::Consumer' => {
  service_host  => 'host.name',
  resource_path => '/path/to/my/resource/:id'
  timeout       => 10,
};

content_type

By default the content type is set to "application/json"

header_exclude

Acts as a filter, will exclude any header information.

header_exclude => {
  post => 'X-Foo',
}

resource_path

This is the path of the resource. IE:

/foo/bar/:id

The :id is a route parameter which will be filled in as specified by the
"route_params" hashref.

retry

This is an explicit retry. Even if the service times out, it will retry
using this value. This retry is different than what L<REST::Consumer> offers.

service_host

The hostname to the service

service_port

The port for the hostname.

timeout

Configuration level timeout. This is global on each request.

useragent_class

Experimental way of overriding L<REST::Consumer>'s useragent. Right now
MooseX::REST::Consumer uses L<LWP::UserAgent>

METHODS

get( route_params => {...}, params => {...} )

Will use REST::Consumer::get to lookup a resource by
supplied resource_path and substitution of route_params

post( route_params => {...}, content => '...' )

Will perform a POST request with REST::Consumer::post.
The data will the Content-Type of application/json by default.

Other supported HTTP methods

DELETE and PUT: delete(%params) and put(%params)

Supported Method Parameters

route_params => {...}

These will be substituted into the package route definition.

params => {...}

Passed into L<REST::Consumer> as a set of key/value
query parameters.

headers => {...}

Any extra HTTP request headers to send. 

content => ''

Passed into L<REST::Consumer>. This is the body content of a request.

timeout => ''

Timeout override per request.

Note that the 'timeout' is subject to interpretation
by your underlying UserAgent class.  For example,
LWP::UserAgent treats the timeout as being
C<per-request>. This means that if you specify a timeout
of 5 seconds and issue a request using LWP::UserAgent,
each request that the UserAgent makes to fulfill your
request will have its own timeout of 5 seconds.

This becomes important if the API that you are talking to
starts giving you 3xx redirects: while you might expect a
timeout to occur within 5 seconds, the API might instruct
your UserAgent to make a few subsequent requests, and each
one will have your initial timeout applied to it.

Different UserAgent classes implement timeouts
differently. L<LWP::UserAgent::Paranoid>, for example,
has a global timeout value, where all requests must be
fulfilled within C<timeout> clock seconds.

Response Object

The response object is created and passed back whenever
any of the supported HTTP methods are called. 
See L<MooseX::Role::REST::Consumer::Response>.

SEE ALSO

REST::Consumer, MooseX::Role::Parameterized, Moose

AUTHORS

The Shutterstock Webstack Team and alumni (Logan Bell,
Jon Hogue, Vishal Kajjam, Belden Lyman, Nikolay Martynov, and
Kurt Starsinic).

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Shutterstock Inc.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.