.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "REST::Client 3pm"
.TH REST::Client 3pm "2016-04-17" "perl v5.22.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
REST::Client \- A simple client for interacting with RESTful http/https resources
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use REST::Client;
\& 
\& #The basic use case
\& my $client = REST::Client\->new();
\& $client\->GET(\*(Aqhttp://example.com/dir/file.xml\*(Aq);
\& print $client\->responseContent();
\&  
\& #A host can be set for convienience
\& $client\->setHost(\*(Aqhttp://example.com\*(Aq);
\& $client\->PUT(\*(Aq/dir/file.xml\*(Aq, \*(Aq<example>new content</example>\*(Aq);
\& if( $client\->responseCode() eq \*(Aq200\*(Aq ){
\&     print "Updated\en";
\& }
\&  
\& #custom request headers may be added
\& $client\->addHeader(\*(AqCustomHeader\*(Aq, \*(AqValue\*(Aq);
\&  
\& #response headers may be gathered
\& print $client\->responseHeader(\*(AqResponseHeader\*(Aq);
\&  
\& #X509 client authentication
\& $client\->setCert(\*(Aq/path/to/ssl.crt\*(Aq);
\& $client\->setKey(\*(Aq/path/to/ssl.key\*(Aq);
\&  
\& #add a CA to verify server certificates
\& $client\->setCa(\*(Aq/path/to/ca.file\*(Aq);
\&  
\& #you may set a timeout on requests, in seconds
\& $client\->setTimeout(10);
\&  
\& #options may be passed as well as set
\& $client = REST::Client\->new({
\&         host    => \*(Aqhttps://example.com\*(Aq,
\&         cert    => \*(Aq/path/to/ssl.crt\*(Aq,
\&         key     => \*(Aq/path/to/ssl.key\*(Aq,
\&         ca      => \*(Aq/path/to/ca.file\*(Aq,
\&         timeout => 10,
\&     });
\& $client\->GET(\*(Aq/dir/file\*(Aq, {CustomHeader => \*(AqValue\*(Aq});
\&  
\& # Requests can be specificed directly as well
\& $client\->request(\*(AqGET\*(Aq, \*(Aq/dir/file\*(Aq, \*(Aqrequest body content\*(Aq, {CustomHeader => \*(AqValue\*(Aq});
\&
\& # Requests can optionally automatically follow redirects and auth, defaults to
\& # false 
\& $client\->setFollow(1);
\&
\& #It is possible to access the L<LWP::UserAgent> object REST::Client is using to
\& #make requests, and set advanced options on it, for instance:
\& $client\->getUseragent()\->proxy([\*(Aqhttp\*(Aq], \*(Aqhttp://proxy.example.com/\*(Aq);
\&  
\& # request responses can be written directly to a file 
\& $client\->setContentFile( "FileName" );
\&
\& # or call back method
\& $client\->setContentFile( \e&callback_method );
\& # see LWP::UserAgent for how to define callback methods
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
REST::Client provides a simple way to interact with \s-1HTTP\s0 RESTful resources.
.SH "METHODS"
.IX Header "METHODS"
.SS "Construction and setup"
.IX Subsection "Construction and setup"
\fInew ( [%$config] )\fR
.IX Subsection "new ( [%$config] )"
.PP
Construct a new REST::Client. Takes an optional hash or hash reference or
config flags.  Each config flag also has get/set accessors of the form
getHost/setHost, getUseragent/setUseragent, etc.  These can be called on the
instantiated object to change or check values.
.PP
The config flags are:
.IP "host" 4
.IX Item "host"
A default host that will be prepended to all requests.  Allows you to just
specify the path when making requests.
.Sp
The default is undef \- you must include the host in your requests.
.IP "timeout" 4
.IX Item "timeout"
A timeout in seconds for requests made with the client.  After the timeout the
client will return a 500.
.Sp
The default is 5 minutes.
.IP "cert" 4
.IX Item "cert"
The path to a X509 certificate file to be used for client authentication.
.Sp
The default is to not use a certificate/key pair.
.IP "key" 4
.IX Item "key"
The path to a X509 key file to be used for client authentication.
.Sp
The default is to not use a certificate/key pair.
.IP "ca" 4
.IX Item "ca"
The path to a certificate authority file to be used to verify host
certificates.
.Sp
The default is to not use a certificates authority.
.IP "pkcs12" 4
.IX Item "pkcs12"
The path to a \s-1PKCS12\s0 certificate to be used for client authentication.
.IP "pkcs12password" 4
.IX Item "pkcs12password"
The password for the \s-1PKCS12\s0 certificate specified with 'pkcs12'.
.IP "follow" 4
.IX Item "follow"
Boolean that determins whether REST::Client attempts to automatically follow
redirects/authentication.
.Sp
The default is false.
.IP "useragent" 4
.IX Item "useragent"
An LWP::UserAgent object, ready to make http requests.
.Sp
REST::Client will provide a default for you if you do not set this.
.PP
\fIaddHeader ( \f(CI$header_name\fI, \f(CI$value\fI )\fR
.IX Subsection "addHeader ( $header_name, $value )"
.PP
Add a custom header to any requests made by this client.
.PP
\fIbuildQuery ( [...] )\fR
.IX Subsection "buildQuery ( [...] )"
.PP
A convienience wrapper around URI::query_form for building query strings from a
variety of data structures. See \s-1URI\s0
.PP
Returns a scalar query string for use in URLs.
.SS "Request Methods"
.IX Subsection "Request Methods"
Each of these methods makes an \s-1HTTP\s0 request, sets the internal state of the
object, and returns the object.
.PP
They can be combined with the response methods, such as:
.PP
.Vb 1
\& print $client\->GET(\*(Aq/search/?q=foobar\*(Aq)\->responseContent();
.Ve
.PP
\fI\s-1GET \s0( \f(CI$url\fI, [%$headers] )\fR
.IX Subsection "GET ( $url, [%$headers] )"
.PP
Preform an \s-1HTTP GET\s0 to the resource specified. Takes an optional hashref of custom request headers.
.PP
\fI\s-1PUT \s0($url, [$body_content, %$headers] )\fR
.IX Subsection "PUT ($url, [$body_content, %$headers] )"
.PP
Preform an \s-1HTTP PUT\s0 to the resource specified. Takes an optional body content and hashref of custom request headers.
.PP
\fI\s-1PATCH \s0( \f(CI$url\fI, [$body_content, %$headers] )\fR
.IX Subsection "PATCH ( $url, [$body_content, %$headers] )"
.PP
Preform an \s-1HTTP PATCH\s0 to the resource specified. Takes an optional body content and hashref of custom request headers.
.PP
\fI\s-1POST \s0( \f(CI$url\fI, [$body_content, %$headers] )\fR
.IX Subsection "POST ( $url, [$body_content, %$headers] )"
.PP
Preform an \s-1HTTP POST\s0 to the resource specified. Takes an optional body content and hashref of custom request headers.
.PP
\fI\s-1DELETE \s0( \f(CI$url\fI, [%$headers] )\fR
.IX Subsection "DELETE ( $url, [%$headers] )"
.PP
Preform an \s-1HTTP DELETE\s0 to the resource specified. Takes an optional hashref of custom request headers.
.PP
\fI\s-1OPTIONS \s0( \f(CI$url\fI, [%$headers] )\fR
.IX Subsection "OPTIONS ( $url, [%$headers] )"
.PP
Preform an \s-1HTTP OPTIONS\s0 to the resource specified. Takes an optional hashref of custom request headers.
.PP
\fI\s-1HEAD \s0( \f(CI$url\fI, [%$headers] )\fR
.IX Subsection "HEAD ( $url, [%$headers] )"
.PP
Preform an \s-1HTTP HEAD\s0 to the resource specified. Takes an optional hashref of custom request headers.
.PP
\fIrequest ( \f(CI$method\fI, \f(CI$url\fI, [$body_content, %$headers] )\fR
.IX Subsection "request ( $method, $url, [$body_content, %$headers] )"
.PP
Issue a custom request, providing all possible values.
.SS "Response Methods"
.IX Subsection "Response Methods"
Use these methods to gather information about the last requset
performed.
.PP
\fIresponseCode ()\fR
.IX Subsection "responseCode ()"
.PP
Return the \s-1HTTP\s0 response code of the last request
.PP
\fIresponseContent ()\fR
.IX Subsection "responseContent ()"
.PP
Return the response body content of the last request
.PP
\fI\fIresponseHeaders()\fI\fR
.IX Subsection "responseHeaders()"
.PP
Returns a list of \s-1HTTP\s0 header names from the last response
.PP
\fIresponseHeader ( \f(CI$header\fI )\fR
.IX Subsection "responseHeader ( $header )"
.PP
Return a \s-1HTTP\s0 header from the last response
.PP
\fIresponseXpath ()\fR
.IX Subsection "responseXpath ()"
.PP
A convienience wrapper that returns a XML::LibXML xpath context for the body content.  Assumes the content is \s-1XML.\s0
.SH "TODO"
.IX Header "TODO"
Caching, content-type negotiation, readable handles for body content.
.SH "AUTHOR"
.IX Header "AUTHOR"
Miles Crawford, <mcrawfor@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008 \- 2010 by Miles Crawford
.PP
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.