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-2017 by Shutterstock Images, LLC.

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