/ 
Role-REST-Client-0.19
River stage two • 21 direct dependents • 22 total dependents
/ Role::REST::Client

NAME

Role::REST::Client - REST Client Role

VERSION

version 0.19

SYNOPSIS

{
	package RESTExample;

	use Moose;
	with 'Role::REST::Client';

	sub bar {
		my ($self) = @_;
		my $res = $self->post('/foo/bar/baz', {foo => 'bar'});
		my $code = $res->code;
		my $data = $res->data;
		return $data if $code == 200;
   }

}

my $foo = RESTExample->new(
	server =>      'http://localhost:3000',
	type   =>      'application/json',
	clientattrs => {timeout => 5},
);

$foo->bar;

# controller
sub foo : Local {
	my ($self, $c) = @_;
	my $res = $c->model('MyData')->post('/foo/bar/baz', {foo => 'bar'});
	my $code = $res->code;
	my $data = $res->data;
	...
}

DESCRIPTION

This REST Client role makes REST connectivity easy.

Role::REST::Client will handle encoding and decoding when using the HTTP verbs.

GET
HEAD
PUT
POST
DELETE
OPTIONS

Currently Role::REST::Client supports these encodings

application/json
application/x-www-form-urlencoded
application/xml
application/yaml

x-www-form-urlencoded only works for GET and POST, and only for encoding, not decoding.

NAME

Role::REST::Client - REST Client Role

METHODS

methods

Role::REST::Client implements the standard HTTP 1.1 verbs as methods

These methods can NOT have a request body

get
head

These methods can take a request body.

post
put
delete
options

All methods take these parameters

url - The REST service
data - The data structure (hashref, arrayref) to send. The data will be encoded
	according to the value of the I<type> attribute.
args - hashref with arguments to augment the way the call is handled.

args - the optional argument parameter can have these entries

deserializer - if you KNOW that the content-type of the response is incorrect,
you can supply the correct content type, like
my $res = $self->post('/foo/bar/baz', {foo => 'bar'}, {deserializer => 'application/yaml'});

preserve_headers - set this to true if you want to keep the headers between calls

All methods return a response object dictated by _rest_response_class. Set to Role::REST::Client::Response by default.

ATTRIBUTES

user_agent

sub _build_user_agent { HTTP::Thin->new }

A User Agent object which has a ->request method suitably compatible with HTTP::Tiny. It should accept arguments like this: $ua->request($method, $uri, $opts), and needs to return a hashref as HTTP::Tiny does, or an HTTP::Response object. To set your own default, use a _build_user_agent method.

server

URL of the REST server.

e.g. 'http://localhost:3000'

type

MIME Content-Type header,

e.g. application/json

persistent_headers

$self->set_persistent_header('Header' => 'foo', ... );
$self->get_persistent_header('Header-Name');
$self->has_no_persistent_headers;
$self->clear_persistent_headers;

A hashref containing headers you want to use for all requests. Use the methods described above to manipulate it.

To set your own defaults, override the default or call set_persistent_header() in your BUILD method.

has '+persistent_headers' => (
  default => sub { ... },
);

httpheaders

$self->set_header('Header' => 'foo', ... );
$self->get_header('Header-Name');
$self->has_no_headers;
$self->clear_headers;

You can set any http header you like with set_header, e.g. $self->set_header($key, $value) but the content-type header will be overridden.

http_headers will be reset after each request, unless there's a reserve_headers argument, but it's a hack. The recommended way to keep headers across requests is to store them in the persistent_headers.

$self->httpheaders will return the combined hashref of persistent_headers and what's been added with set_header.

For historical reasons, the two methods clear_headers and reset_headers are equal. Both will clear the headers for the current request, but NOT the persistent headers.

To clear ALL headers, use

$self->clear_all_headers;

clientattrs

Attributes to feed the user agent object (which defaults to HTTP::Thin)

e.g. {timeout => 10}

serializer_class

You can override the serializer class and use your own. Default is 'Role::REST::Client::Serializer'

serializer_options

Options for the serializer instantiation.

CONTRIBUTORS

Breno G. de Oliveira, <garu@cpan.org>

Mark Stosberg, <mark@stosberg.com>

Matt Phillips, (cpan:MATTP) <mattp@cpan.org>

Wallace Reis, <wallace@reis.me>

BUGS

Please report any bugs or feature requests to bug-role-rest-client at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Role-REST-Client.

AUTHOR

Kaare Rasmussen <kaare at cpan dot org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Kaare Rasmussen.

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