/ 
WWW-Resource-0.01
River stage zero No dependents
/ WWW::Resource

NAME

WWW::Resource - Quickly create a REST style web service.

SYNOPSIS

package ResourceName;

use HTTP::Status
use WWW::Resource;
@ISA = qw( WWW::Resource );

sub GET {
  return RC_OK, "Congratulations you have accessed this resource.";
}

ResourceName->run;

=EOF

In a browser:
http[s]://localhost/resourcename

Congratulations you have accessed this resource.

DESCRIPTION

This module ties together a small set of serializers and a FastCGI interface to a load balancer, in a convenient package allowing you to quickly deploy resources to the network with a bare minimum of coding. If you have installed a web server and configured it to use FastCGI - which takes about fifteen minutes if you use lighttpd - in about two more minutes you can expose a REST-style web service.

Userspace? No problem. SSL? No problem. Load balancing? Got it covered.

Please see "INSTALL.REST-FRAMEWORK" in the build directory for more info about the full system installation.

There are two ways to return your response to the caller (a browser or other program). You can simply return any Perl data structure, which will be serialized into the requested format (XML or JSON or "browser prettyprint" format), or you can actually construct a page yourself, perhaps even using CGI.pm to help, and return a single string. Any single string will be transmitted verbatim (after the headers) to the caller.

To access the resource via a browser or other program, decide which serialization format you want and add "format=xml" or "format=json" or "format=browser" to the query string part of the URI. For example, http://localhost/resourcename?format=browser.

Whenever you define a GET, PUT, POST, or DELETE function, those will be installed automatically as handlers. In fact you can override any HTTP method whatsoever, but in practice no one should need more than these for a REST style service. These functions will recieve as their only argument a hash reference to the parsed query string. For instance, the "format=browser" arg will be there, as well as any others. This is only for convenience, since these items are available through $ENV{QUERY_STRING}.

OVERLOADABLE METHODS

All HTTP methods are overloadable. In practice you will not need more than GET, POST, PUT, and DELETE.

In addition, ttl() and browserprint can be defined. ttl() should return a time-to-live value in seconds. Each of your processes will then exit after recieving a request after ttl has been exceeded, and the FastCGI process manager will start a new instance. Define browserprint() if you want to do your own pretty printing to the browser, ie when your service is called with format=browser. The default one is incredibly stupid.

EXAMPLE

Here is a fully functioning REST style web service, implementing all four CRUD operations (create retrieve update delete) via the analogous POST GET PUT DELETE http methods. This resource consists of all the PATH_INFO / QUERY_STRING pairs it has seen via previous requests, in the form of a hash.

package ResourceName;

use HTTP::Status
use WWW::Resource;
@ISA = qw( WWW::Resource );

my %resource = (); # no resources yet

# Time-to-live - default 1 hr - optional. You can 
# also set this in the load balancer config file, but here
# is finer-grained control if you need it.
sub ttl { 60*60 };

# start the event loop
ResourceName->run;

# The above will run as-is, but won't do much.
# Create the following CRUD-analogous methods for different responses.

# "Retrieve"
sub GET {

  # Return the specified value, if it exists
  if(exists $resource{$ENV{PATH_INFO}}){
    return RC_OK, $resource{$ENV{PATH_INFO}};
  }

  # No named resource specified? Return them all.
  elsif($ENV{PATH_INFO}){ 
    return RC_OK, \%resource;
  }

  # A named resource that's not there is an error
  return RC_NOT_FOUND;
}


# "Update"
sub PUT {
  my ($rkey, $rval) = ($ENV{PATH_INFO}, $ENV{QUERY_STRING});
  if(exists $resource{$rkey}){
    $resource{$rkey} = $rval;
    return RC_UPDATED;
  }
  $resource{$rkey} = $rval;
  return RC_CREATED;
}

# "Create"
sub POST {
  my ($rkey, $rval) = ($ENV{PATH_INFO}, $ENV{QUERY_STRING});
  $resource{$rkey} = $rval;
  return RC_CREATED;
}

# "Delete"
sub DELETE {
  my ($rkey, $rval) = ($ENV{PATH_INFO}, $ENV{QUERY_STRING});
  if(exists $resource{$rkey}){
    delete $resource{$rkey};
    return RC_DELETED;
  }
  return RC_NOT_FOUND;
}

REQUIRES

A web server with FastCGI support, lighttpd is recommended. FCGI LWP JSON XML::Dumper

AUTHOR

Ira Woodhead, <ira at sweetpota dot to>

COPYRIGHT AND LICENSE

Copyright (C) 2006 by Ira Woodhead

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.