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

VERSION

10       version 281
11

SYNOPSIS

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

DESCRIPTION

72       REST::Client provides a simple way to interact with HTTP RESTful
73       resources.
74

METHODS

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

TODO

216       Caching, content-type negotiation, readable handles for body content.
217

AUTHORS

219       •   Miles Crawford <mcrawfor@cpan.org>
220
221       •   Kevin L. Kane <kkane@cpan.org>
222

224       This software is copyright (c) 2008 by Miles Crawford.
225
226       This is free software; you can redistribute it and/or modify it under
227       the same terms as the Perl 5 programming language system itself.
228
229
230
231perl v5.36.0                      2023-01-20                   REST::Client(3)
Impressum