NAME

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

SYNOPSIS

 use REST::Client;
 
 #The basic use case
 my $client = REST::Client->new();
 $client->GET('http://example.com/dir/file.xml');
 print $client->responseContent();
  
 #A host can be set for convienience
 $client->setHost('http://example.com');
 $client->PUT('/dir/file.xml', '<example>new content</example>');
 if( $client->responseCode() eq '200' ){
     print "Deleted\n";
 }
  
 #custom request headers may be added
 $client->addHeader('CustomHeader', 'Value');
  
 #response headers may be gathered
 print $client->responseHeader('ResponseHeader');
  
 #X509 client authentication
 $client->setCert('/path/to/ssl.crt');
 $client->setKey('/path/to/ssl.key');
  
 #add a CA to verify server certificates
 $client->setCa('/path/to/ca.file');
  
 #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    => 'https://example.com',
         cert    => '/path/to/ssl.crt',
         key     => '/path/to/ssl.key',
         ca      => '/path/to/ca.file',
         timeout => 10,
     });
 $client->GET('/dir/file', {CustomHeader => 'Value'});
  
 #Requests can be specificed directly as well
 $client->request('GET', '/dir/file', 'request body content', {CustomHeader => 'Value'});

DESCRIPTION

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

METHODS

new ( [%$config] )

Construct a new REST::Client. Takes an optional hash or hash reference or config flags:

host

A default host that will be prepended to all requests. Allows you to just specify the path when making requests.

timeout

A timeout in seconds for requests made with the client. After the timeout the client will return a 500.

cert

The path to a X509 certificate file to be used for client authentication.

key

The path to a X509 key file to be used for client authentication.

ca

The path to a certificate authority file to be used to verify host certificates.

GET ( $url, [%$headers] )

Preform an HTTP GET to the resource specified. Takes an optional hashref of custom request headers.

PUT ($url, [$body_content, %$headers] )

Preform an HTTP PUT to the resource specified. Takes an optional body content and hashref of custom request headers.

POST ( $url, [$body_content, %$headers] )

Preform an HTTP POST to the resource specified. Takes an optional body content and hashref of custom request headers.

DELETE ( $url, [%$headers] )

Preform an HTTP DELETE to the resource specified. Takes an optional hashref of custom request headers.

OPTIONS ( $url, [%$headers] )

Preform an HTTP OPTIONS to the resource specified. Takes an optional hashref of custom request headers.

HEAD ( $url, [%$headers] )

Preform an HTTP HEAD to the resource specified. Takes an optional hashref of custom request headers.

addHeader ( $header_name, $value )

Add a custom header to the next request.

request ( $method, $url, [$body_content, %$headers] )

Issue a custom request, providing all possible values.

responseCode ()

Return the HTTP response code of the last request

responseContent ()

Return the response body content of the last request

responseHeader ()

Return the HTTP headers from the last response

buildQuery ( [...] )

A convienience wrapper around URI::query_form for building query strings. See URI

responseXpath ()

A convienience wrapper that returns a XML::LibXML xpath context for the body content. Assumes the content is XML.

TODO

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

AUTHOR

Miles Crawford, <mcrawfor@cpan.org>

COPYRIGHT

Copyright 2008 - 2009 by Miles Crawford.

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