Ira Joseph Woodhead > WWW-Resource-0.01 > WWW::Resource

Download:
WWW-Resource-0.01.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.01   Source  

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.

syntax highlighting: