1REST::Client(3)       User Contributed Perl Documentation      REST::Client(3)
2
3
4

NAME

6       REST::Client - A simple client for interacting with RESTful http/https
7       resources
8

SYNOPSIS

10        use REST::Client;
11
12        #The basic use case
13        my $client = REST::Client->new();
14        $client->GET('http://example.com/dir/file.xml');
15        print $client->responseContent();
16
17        #A host can be set for convienience
18        $client->setHost('http://example.com');
19        $client->PUT('/dir/file.xml', '<example>new content</example>');
20        if( $client->responseCode() eq '200' ){
21            print "Updated\n";
22        }
23
24        #custom request headers may be added
25        $client->addHeader('CustomHeader', 'Value');
26
27        #response headers may be gathered
28        print $client->responseHeader('ResponseHeader');
29
30        #X509 client authentication
31        $client->setCert('/path/to/ssl.crt');
32        $client->setKey('/path/to/ssl.key');
33
34        #add a CA to verify server certificates
35        $client->setCa('/path/to/ca.file');
36
37        #you may set a timeout on requests, in seconds
38        $client->setTimeout(10);
39
40        #options may be passed as well as set
41        $client = REST::Client->new({
42                host    => 'https://example.com',
43                cert    => '/path/to/ssl.crt',
44                key     => '/path/to/ssl.key',
45                ca      => '/path/to/ca.file',
46                timeout => 10,
47            });
48        $client->GET('/dir/file', {CustomHeader => 'Value'});
49
50        # Requests can be specificed directly as well
51        $client->request('GET', '/dir/file', 'request body content', {CustomHeader => 'Value'});
52
53        # Requests can optionally automatically follow redirects and auth, defaults to
54        # false
55        $client->setFollow(1);
56
57        #It is possible to access the L<LWP::UserAgent> object REST::Client is using to
58        #make requests, and set advanced options on it, for instance:
59        $client->getUseragent()->proxy(['http'], 'http://proxy.example.com/');
60
61        # request responses can be written directly to a file
62        $client->setContentFile( "FileName" );
63
64        # or call back method
65        $client->setContentFile( \&callback_method );
66        # see LWP::UserAgent for how to define callback methods
67

DESCRIPTION

69       REST::Client provides a simple way to interact with HTTP RESTful
70       resources.
71

METHODS

73   Construction and setup
74       new ( [%$config] )
75
76       Construct a new REST::Client. Takes an optional hash or hash reference
77       or config flags.  Each config flag also has get/set accessors of the
78       form getHost/setHost, getUseragent/setUseragent, etc.  These can be
79       called on the instantiated object to change or check values.
80
81       The config flags are:
82
83       host
84           A default host that will be prepended to all requests.  Allows you
85           to just specify the path when making requests.
86
87           The default is undef - you must include the host in your requests.
88
89       timeout
90           A timeout in seconds for requests made with the client.  After the
91           timeout the client will return a 500.
92
93           The default is 5 minutes.
94
95       cert
96           The path to a X509 certificate file to be used for client
97           authentication.
98
99           The default is to not use a certificate/key pair.
100
101       key The path to a X509 key file to be used for client authentication.
102
103           The default is to not use a certificate/key pair.
104
105       ca  The path to a certificate authority file to be used to verify host
106           certificates.
107
108           The default is to not use a certificates authority.
109
110       pkcs12
111           The path to a PKCS12 certificate to be used for client
112           authentication.
113
114       pkcs12password
115           The password for the PKCS12 certificate specified with 'pkcs12'.
116
117       follow
118           Boolean that determins whether REST::Client attempts to
119           automatically follow redirects/authentication.
120
121           The default is false.
122
123       useragent
124           An LWP::UserAgent object, ready to make http requests.
125
126           REST::Client will provide a default for you if you do not set this.
127
128       addHeader ( $header_name, $value )
129
130       Add a custom header to any requests made by this client.
131
132       buildQuery ( [...] )
133
134       A convienience wrapper around URI::query_form for building query
135       strings from a variety of data structures. See URI
136
137       Returns a scalar query string for use in URLs.
138
139   Request Methods
140       Each of these methods makes an HTTP request, sets the internal state of
141       the object, and returns the object.
142
143       They can be combined with the response methods, such as:
144
145        print $client->GET('/search/?q=foobar')->responseContent();
146
147       GET ( $url, [%$headers] )
148
149       Preform an HTTP GET to the resource specified. Takes an optional
150       hashref of custom request headers.
151
152       PUT ($url, [$body_content, %$headers] )
153
154       Preform an HTTP PUT to the resource specified. Takes an optional body
155       content and hashref of custom request headers.
156
157       PATCH ( $url, [$body_content, %$headers] )
158
159       Preform an HTTP PATCH to the resource specified. Takes an optional body
160       content and hashref of custom request headers.
161
162       POST ( $url, [$body_content, %$headers] )
163
164       Preform an HTTP POST to the resource specified. Takes an optional body
165       content and hashref of custom request headers.
166
167       DELETE ( $url, [%$headers] )
168
169       Preform an HTTP DELETE to the resource specified. Takes an optional
170       hashref of custom request headers.
171
172       OPTIONS ( $url, [%$headers] )
173
174       Preform an HTTP OPTIONS to the resource specified. Takes an optional
175       hashref of custom request headers.
176
177       HEAD ( $url, [%$headers] )
178
179       Preform an HTTP HEAD to the resource specified. Takes an optional
180       hashref of custom request headers.
181
182       request ( $method, $url, [$body_content, %$headers] )
183
184       Issue a custom request, providing all possible values.
185
186   Response Methods
187       Use these methods to gather information about the last requset
188       performed.
189
190       responseCode ()
191
192       Return the HTTP response code of the last request
193
194       responseContent ()
195
196       Return the response body content of the last request
197
198       responseHeaders()
199
200       Returns a list of HTTP header names from the last response
201
202       responseHeader ( $header )
203
204       Return a HTTP header from the last response
205
206       responseXpath ()
207
208       A convienience wrapper that returns a XML::LibXML xpath context for the
209       body content.  Assumes the content is XML.
210

TODO

212       Caching, content-type negotiation, readable handles for body content.
213

AUTHOR

215       Miles Crawford, <mcrawfor@cpan.org>
216

218       Copyright 2008 - 2010 by Miles Crawford
219
220       This program is free software; you can redistribute it and/or modify it
221       under the same terms as Perl itself.
222
223
224
225perl v5.32.1                      2021-01-27                   REST::Client(3)
Impressum