Provided by: librest-client-perl_273-1_all bug

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 "Updated\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'});

        # 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(['http'], 'http://proxy.example.com/');

        # request responses can be written directly to a file
        $client->setContentFile( "FileName" );

        # or call back method
        $client->setContentFile( \&callback_method );
        # see LWP::UserAgent for how to define callback methods

DESCRIPTION

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

METHODS

   Construction and setup
       new ( [%$config] )

       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.

       The config flags are:

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

           The default is undef - you must include the host in your requests.

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

           The default is 5 minutes.

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

           The default is to not use a certificate/key pair.

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

           The default is to not use a certificate/key pair.

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

           The default is to not use a certificates authority.

       pkcs12
           The path to a PKCS12 certificate to be used for client authentication.

       pkcs12password
           The password for the PKCS12 certificate specified with 'pkcs12'.

       follow
           Boolean that determins whether REST::Client attempts to automatically follow
           redirects/authentication.

           The default is false.

       useragent
           An LWP::UserAgent object, ready to make http requests.

           REST::Client will provide a default for you if you do not set this.

       addHeader ( $header_name, $value )

       Add a custom header to any requests made by this client.

       buildQuery ( [...] )

       A convienience wrapper around URI::query_form for building query strings from a variety of
       data structures. See URI

       Returns a scalar query string for use in URLs.

   Request Methods
       Each of these methods makes an HTTP request, sets the internal state of the object, and
       returns the object.

       They can be combined with the response methods, such as:

        print $client->GET('/search/?q=foobar')->responseContent();

       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.

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

       Preform an HTTP PATCH 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.

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

       Issue a custom request, providing all possible values.

   Response Methods
       Use these methods to gather information about the last requset performed.

       responseCode ()

       Return the HTTP response code of the last request

       responseContent ()

       Return the response body content of the last request

       responseHeaders()

       Returns a list of HTTP header names from the last response

       responseHeader ( $header )

       Return a HTTP header from the last response

       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 - 2010 by Miles Crawford

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