NAME
        REST::Resource      -- Provide base class functionality for RESTful servers.

SYNOPSIS
        package My::Rest::Resource;
        use base "REST::Resource";

        sub new
        {
            my( $class )    = shift;
            my( $this )     = $this->SUPER::new( @_ );
            $this->method( "PUT",   \&Create, "This method handles the creation of My::Rest::Resource." );
            $this->method( "GET",   \&Read,   "This method handles the reading of My::Rest::Resource." );
            $this->method( "POST",  \&Update, "This method handles the updating of My::Rest::Resource." );
            $this->method( "DELETE",\&Delete, "This method handles the deletion of My::Rest::Resource." );
        }

        sub Create  { my( $this ) = shift;  my( $request_interface_instance ) = shift; ... }
        sub Read    { my( $this ) = shift;  my( $request_interface_instance ) = shift; ... }
        sub Update  { my( $this ) = shift;  my( $request_interface_instance ) = shift; ... }
        sub Delete  { my( $this ) = shift;  my( $request_interface_instance ) = shift; ... }

        package main;
        use My::Rest::Resource;

        my( $restful )      = new My::Rest::Resource();
        $restful->handle_request();                         ## One-shot CGI Context

DESCRIPTION
        This is a fork of WWW::Resource 0.01.  The major changes are:

        [] Full OO implementation
        [] Overt abstract base class design
        [] Support of Perl 5.6
        [] Support for use with CGI interface.
        [] Support for HEAD and TRACE.
        [] Method / handler registration to better support
           application-semantics over REST-semantics.

METHOD REGISTRATION
        HTTP method handlers should be members of your derived class and
        expect $this (or $self) as the first parameter.

        sub Create  { my( $this ) = shift;  my( $request_interface_instance ) = shift; ... }
        sub Read    { my( $this ) = shift;  my( $request_interface_instance ) = shift; ... }
        sub Update  { my( $this ) = shift;  my( $request_interface_instance ) = shift; ... }
        sub Delete  { my( $this ) = shift;  my( $request_interface_instance ) = shift; ... }

REQUEST INTERFACE INSTANCE
        $request_interface_instance is a wrapper for your favorite Common
        Gateway Interface implementation.  Mine is CGI.pm for server-side
        request interrogation and server-side response.

        If you don't like this, create a class modeled after REST::Request
        and register it with:

        my( $restful ) = new REST::Resource( request_interface => new My::REST::Request() );

        The REST::Resource constructor will validate that
        My::REST::Request implements the requisite methods new(), http(),
        param() and header() and then only use these methods to interace
        with the Common Gateway Interface variables.

REQUESTED RETURNED CONTENT-TYPE:
        The requesting client is responsible for specifying the
        returned Content-Type: header in one of two ways.

        [] Via the "Accept: application/xml" HTTP header.
        [] Via the CGI query parameter ?format=xml

        The Accept: header is preferred as it is semantically
        cleaner, but the CGI query parameter is also supported in
        recognition of the fact that sometimes it is easier to affect the
        request URL than it is to get at and specify the HTTP headers.

DEFAULT SUPPORTED CONTENT TYPES
        The supported content types provided by the base class are:

        []  ?format=xml     or      Accept: application/xml
        []  ?format=json    or      Accept: text/javascript
        []  ?format=html    or      Accept: text/html

        HTML will be returned if the requestor appears to be a browser and
        no format is specified.

        XML will be returned if the requestor does NOT appear to be a
        browser and no format is specified.

AUTHOR
        frotz@acm.org                               Fork of WWW::Resource into REST::Resource.

CREDITS
        Ira Woodhead <ira at sweetpota dot to>      For his WWW::Resource implementation.

METHODS
  new()
    USAGE:

        my( $restful ) = new REST::Resource();
        $restful->method( "GET", \&get_handler );
        $restful->handle_request();

        my( $restful ) = new REST::Resource( request_interface => new REST::Request() );

    DESCRIPTION:

        Create an instance of a REST::Resource, or one of its
        derived classes.

        If you need a specific implementation of the REST::Request
        interface, pass it in as shown in the second constructor call.

  run()		CAUTION
    USAGE:

        my( $restful )      = new REST::Resource( new CGI::Fast() );
        $restful->run();

        my( $restful )      = new Your::WWW::Resource::Implementation( new CGI::Fast() );
        $restful->run();

    DESCRIPTION:

        This method will run a CGI::Fast instance.  It delegates request
        interpolation to the registered request instance via the
        constructor.  The default is a shim derived class of CGI.pm.

    WWW::RESOURCE COMPATIBILITY:

        If your derived class provides the WWW::Resource suggested
        callbacks browserprint() and ttl(), this method will honor those
        and fold in the new code hook mechanism.

    WARNING:

        If your derived class contains the method "browserprint()",
        the calling semantics for _all_ methods will be \%query.

            $instance->$method( \%query_hash );

        If your derived class does NOT contain the method "browserprint()",
        it is assumed that you are using the new calling semantics where
        you method handler is passed the request instance.

            $instance->$method( $request_instance );

        Thus ref( $arg ) will be "HASH" for the old style and an object
        reference for the new style.

  handle_request()
    USAGE:

        my( $restful ) = new REST::Resource( request_instance => new REST::Request() );
        $restful->handle_request();                         ## Implicit
        $restful->handle_request( new REST::Request() );    ## Explicit
        $restful->handle_request( new CGI() );              ## Explicit

    DESCRIPTION:

        This method runs a single action handler.  Optionally pass in the
        CGI request to be handled.

  method()
    USAGE:

        my( $coderef ) = $restful->method( "GET" );         ## OR
        my( $method )  = $restful->method( "GET", \&get_handler, $description );

        $restful->$method( $request_interface_instance );

    DESCRIPTION:

        This accessor/mutator allows the caller to register or change the
        implementation behavior for a given HTTP method handler.  The standard
        event handlers that are pre-registered are:

            GET
            PUT
            POST
            DELETE
            TRACE
            HEAD

        Additionally, the following pseudo-methods provide over-ride control
        to derived class implementors.

            authenticate

        Unless otherwise overridden, the default implementation for each
        of these methods is REST::Resource->unimplemented().

  format()
    USAGE:

        my( $format ) = $restful->format( "xml" );          ## OR
        $description   = $restful->format( "xml", \&format_xml, $description );

        $restful->$format( $request_interface_instance, $status, $data );

    DESCRIPTION:

        This accessor/mutator allows the caller to register or change the
        implementation behavior for a given output format.

  description()
    USAGE:

        my( $restful )      = new REST::Resource();
        my( $description )  = $restful->description( $name );

    DESCRIPTION:

        This accessor/mutator allows the caller to register or change the
        description for a given HTTP method handler or output format.

        This is used by REST::Resource->api() to provide a description
        of the API.

    PARAMETERS:

        $type       -- "methods" or "formats"
        $name       -- See the names appropriate for the given $type.
        $description-- The description to be set (or returned).

  api()
    USAGE:

        my( $status, $data ) = $this->api( $request_interface_instance );

    DESCRIPTION:

        This method generates a resultset that can be returned through
        $this->_return_result( $status, $data );

  authenticate()
    USAGE:

        my( $status, $data ) = $this->authenticate( $request_interface_instance );

    DESCRIPTION:

        This method may be overridden by a derived class that requires
        HTTP request authentication.

    STATUS VALUES:

        RC_OK               (200)   -- Accept provided credentials, if any.
        RC_UNAUTHORIZED     (401)   -- Prompt user for credentials via dialog box.
        RC_FORBIDDEN        (403)   -- Reject provided credentials.

    DERIVED IMPLEMENTATIONS:

        This method may be overridden in the derived class in order to
        require a specific set of credentials.

  format_xml()
    USAGE:

        print $this->format_xml( $request_interface_instance, $status, $data );

    DESCRIPTION:

        This method will format $data as XML via XML::Dumper with an
        included in-document DTD.

  format_text()
    USAGE:

        print $this->format_text( $request_interface_instance, $status, $data );

    DESCRIPTION:

        Use Data::Dumper to emit $data in text/plain format.

  format_html()
    USAGE:

        print $this->format_html( $request_interface_instance, $status, $data );

    DESCRIPTION:

        Use Data::Dumper to emit $data, then translate it via simple <pre>
        tags with limited CSS to control the font-size.

  format_json()
    USAGE:

        print $this->format_json( $request_interface_instance, $status, $data );

    DESCRIPTION:

        This method will format $data in JSON (JavaScript Object
        Notation).

  unimplemented()
    USAGE:

        N/A

    DESCRIPTION:

        This method is invoked if an unregistered HTTP REQUEST_METHOD is
        invoked.

  default_format()
    USAGE:

        my( $format )       = $this->default_format( $request_interface_instance );
        print $this->$format( $status, $data );

    DESCRIPTION:

        This method will return the requested format.  We look in two
        places.  The first is in the query parameter list for the
        parameter "format".  If that is defined, we return that value.

        Otherwise, we scan through the list of q=1.0 Accept: headers and
        return the first matching MIME-type.

    SAMPLE OPERA Accept: / User-Agent: HEADERS: Accept: text/html,
    application/xml;q=0.9, application/xhtml+xml, image/png, image/jpeg,
    image/gif, image/x-xbitmap, */*;q=0.1 User-Agent: Opera/9.10 (X11; Linux
    i686; U; en)

    SAMPLE FIREFOX Accept: / User-Agent: HEADERS: Accept: text/xml,
    application/xml, application/xhtml+xml, text/html; q=0.9, text/plain;
    q=0.8, image/png, */*; q=0.5 User-Agent: Mozilla/5.0 (Windows; U;
    Windows NT 5.1; en-US; rv:1.8.1.3) Gecko/20070309 Firefox/2.0.0.3

    SAMPLE MSIE Accept: / User-Agent: HEADERS: Accept: image/gif,
    image/x-xbitmap, image/jpeg, image/pjpeg, application/x-shockwave-flash,
    application/vnd.ms-powerpoint, application/vnd.ms-excel,
    application/msword, */* User-Agent: Mozilla/4.0 (compatible; MSIE 6.0;
    Windows NT 5.1; SV1; .NET CLR 1.1.4322; .NET CLR 2.0.50727)

    SUGGESTIONS FOR JSON DEVELOPERS: Use "Accept: text/javascript" or
    "?format=json" to get JSON output. The default algorithm will presume
    that the client is a human behind a browser and try to encourage html.

    SUGGESTIONS FOR AJAX DEVELOPERS: Use "Accept: application/xml" or
    "?format=xml" to get XML output. The default algorithm will presume that
    the client is a human behind a browser and try to encourage html.

  get_request()
    USAGE:

        my( $request )      = $restful->get_request();

    DESCRIPTION:

        Return a new request_interface instance.  This instance must
        support the methods: new(), http(), param() and header().

    SEE ALSO:

        REST::Request

  _return_result()	PRIVATE
    USAGE:

        $this->_return_result( $request_interface_instance, $http_status, $data );

    DESCRIPTION:

        This method is handed output of a given REQUEST_METHOD handler and
        is responsible for appropriate status code emission and $data
        formatting.

  SEE ALSO
        WWW::Resource
        http://www.peej.co.uk/articles/restfully-delicious.html
        http://www.xfront.com/REST-Web-Services.html
        http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

NAME
        REST::Request

SYNOPSIS
        use REST::Resource;

        sub main
        {
            my( $restul )   = new REST::Resource( request_interface => new REST::Request() );
            ...
        }

DESCRIPTION
        This class provides a standardized interface shim that users can
        implement in order to wrap around their favorite CGI interface
        module so that it can be registered and used by REST::Resource.

        If you prefer some module other than CGI.pm to access server-side
        CGI behavior, then create a module that mimics this interface and
        register it with REST::Resource as shown in the synopsis.

INTERFACE v. ABSTRACT BASE CLASS
        In this case, I prefer Java's interface-style to an abstract base
        class that someone must override.  Since this class derives from
        CGI.pm for its implementation, you may not want that baggage in
        your interface implementation.  Therefore, all you need to do is
        register a class that provides the functionality specified by this
        module.

        Since there isn't really a great Perl-based interface specification,
        REST::Resource will interrogate your registered request_interface
        to ensure that the class provides the minimum / required methods:

            new()
            http()
            param()
            header()

        If you chose to provide an alternate interface implementation,
        these are the methods that must exist before REST::Resource will
        accept your interface.

AUTHOR
        John "Frotz" Fa'atuai
        frotz@acm.org

INTERFACE METHODS
  new()
    USAGE:

        my( $restful )      = new REST::Resource( request_interface => new REST::Request() );
        my( $request )      = new REST::Request();

    DESCRIPTION:

        This method constructs a new instance of the request object.  The
        first usage shows how users should pass this into REST::Resource.
        The second usage shows how you might use this in your unit tests.

    WARNING:

        This constructor plays REST games with CGI.pm by detecting PUT or
        DELETE and transforming the request (temporarily) to POST, then
        reverting back to the original value before returning an instance.
        This allows us to use all of the nice POST processing provided by
        CGI.pm, but for PUT, and DELETE, not just POST.

  http()
    USAGE:

        my( $value )        = $request->http( $variable );

    DESCRIPTION:

        This method extracts the given CGI $variable from the underlying
        $request and returns its $value.

  header()
    USAGE:

        $request->header( %args );

    DESCRIPTION:

        This interface method provides access to the CGI-response header
        functionality.  This method will be called when you have the
        collection of response headers that you want to pass down to your
        base class.

  param()
    USAGE:

        my( $value ) = $request->param( $variable );

    DESCRIPTION:

        This method returns the $value of the CGI request parameter
        $variable.

SEE ALSO
        CGI
        REST::Resource