NAME

POE::Component::Client::REST - Low-level interface for REST calls

VERSION

Version 0.05

SYNOPSIS

This class abstracts away some of the nastier details of talking to a REST service.

    use POE qw(Component::Client::REST::JSON);

    # simple CouchDB example

    POE::Session->create(inline_states => {
      _start => sub {
        $poe_kernel->alias_set('foo');
        my $rest = $_[HEAP]->{rest} = POE::Component::Client::REST::JSON->new;
        $rest->call(GET => 'http://localhost:5984/_all_dbs', callback =>
          [$_[SESSION], 'response']);
      },

      response => sub {
        my ($data, $response) = @_[ARG0, ARG1];
        die $response->status_line unless $response->code == 200;

        print 'Databases: ' . join(', ', @$data) . "\n";
        $poe_kernel->alias_remove('foo');
        $_[HEAP]->{rest}->shutdown();
      },
    });

    $poe_kernel->run();

ATTRIBUTES

Alias

The string to use as the alias for the internal session.

http

The alias of the spawned HTTP object's session. Defaults to something reasonable.

request_cooker

A function which takes a request and cooks it in some fashion, returning a new one (or the same one, modified). Undefined by default, but see POE::Component::Client::REST::JSON.

response_cooker

Similar to the above, but returns a list of things to be passed to the callbacks when a response is received for a particular request.

METHODS

call method, url, keywords

Makes an HTTP request to url via method. The following keyword arguments are accepted (either as a hashref or just as extra argument pairs).

request_cooker

response_cooker

Overrides the object defaults for these values. Explicitly pass undef to specify that no cooking should be done.

query

A hashref of query parameters to be appended as a query string.

content

Data (which may or may not get cooked) to be passed as the request body.

headers

Specify arbitrary headers as an arrayref of key-value pairs.

callback

Either a coderef or an arrayref of two elements (session and state name) to call (or post to) with the (possibly cooked) response to the request.

You can also post to this session's 'call' state for the same result, although in this form the keywords must be a hashref.

spawn kwargs or hashref

new kwargs or hashref

Passes all options to POE::Component::Client::HTTP except for Alias, which is used for our own session. The HTTP session has an alias of "$Alias-HTTP". The default session alias for the internal session is REST-JSON-Session.

shutdown

Calls shutdown on the HTTP client and stops this session. You can also post to the 'shutdown' state for the same result.

AUTHOR

Paul Driver, <frodwith at cpan.org>

BUGS

This was written for use with POE::Component::Client::CouchDB, so it's sort of tailored to that API and probably unsuitable without modification for other purposes. Patches welcome!

COPYRIGHT & LICENSE

Copyright 2008 Paul Driver

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