Apache2-REST

 view release on metacpan or  search on metacpan

lib/Apache2/REST.pm  view on Meta::CPAN

    if ( $@ ){
        die "Cannot find root class $handlerRootClass (from conf Apache2RESTHandlerRootClass): $@\n" ;
    }

    my $topHandler = $handlerRootClass->new() ;
    my $conf = Apache2::REST::Conf->new() ;
    $conf->Apache2RESTErrorOutput($r->dir_config('Apache2RESTErrorOutput') || 'both' );
    $topHandler->conf($conf);

    my @stack = split('\/+' , $uri);
    # Protect against empty fragments.
    @stack = grep { length($_)>0 } @stack ;



    $retCode = $topHandler->handle(\@stack , $req , $resp ) ;

  output:
    ## Load the writer for the given format
    my $defaultWriter = $r->dir_config('Apache2RESTWriterDefault') || 'xml' ;
    my $wClass = $_wtClasses->{$req->requestedFormat()} || $_wtClasses->{$defaultWriter}  ;

lib/Apache2/REST/Handler.pm  view on Meta::CPAN

use Apache2::REST::ErrorOutputRegistry ;

use base qw/Class::AutoAccess/ ;

=head1 NAME

Apache2::REST::Handler - Base class for a resource handler.

=head1 SYNOPSIS

A Handler object is build for each fragment of the URI, and objects are chained via the attibute parent.

You _must_ implement at list one Handler class to handle the root URI of your application and set it in your
apache conf by : PerlSetVar Apache2RESTHandlerRootClass "MyApp::REST::API" (for instance).

You _must_ implement at least one HTTP method (GET,POST,PUT,DELETE ...).

They will be called by the framework like this (for instance):

 $this->GET($request,$response) ;

lib/Apache2/REST/Handler.pm  view on Meta::CPAN

                return HTTP_INTERNAL_SERVER_ERROR ;
            }
            $resp->status($res) ;
            return $res ;
        }else{
            $resp->status(HTTP_UNAUTHORIZED) ;
            $resp->message('method unauthorized') ;
            return HTTP_UNAUTHORIZED ;
        }
    }
    my $fragment = shift @$stack ;
    my $subh = $self->buildNext($fragment , $req ) ;
    unless( $subh ){
        $resp->status(HTTP_NOT_FOUND);
        $resp->message('Resource not found for '.$fragment) ;
        return HTTP_NOT_FOUND ;
    }
    return $subh->handle($stack , $req , $resp ) ;
}

=head2 buildNext

This method is responsible for building the handler handling the next fragment.
It is given the fragment to build an handler for as well as the Request.

The default implementation builds a handler of class $this->class().'::'.$frag 

It _must_ return undef when the resource is not found.

Called like this by the framework:

$this->buildNext($frag , $req ) ;

Overriding use cases:

- Build a dynamic handler.
  For instance if the fragment is an item ID, you might want to build an item handler with this particular item. See L<Apache2::REST::Handler::test> for an example.

- Rerouting outside of the handler classes space.
  If you want to escape the default class resolution mecanism.


=cut

sub buildNext{
    my ( $self , $frag , $req ) = @_ ;
    ## default implementation
    
    my $newC = $self->class().'::'.$frag ;
    eval "require $newC;";
    if ( $@ ){
        warn "Class $newC not found: $@\n" ;
        return undef ;
    }
    return $newC->new($self) ;
}


=head2 isAuth

lib/Apache2/REST/Handler/test.pm  view on Meta::CPAN

sub DELETE{
    my ($self, $req , $resp ) = @_ ;
    $resp->data()->{'test_mess'} = 'This is a DELETE test message' ;
    ## It is OK
    return Apache2::Const::HTTP_OK ;
}


=head2 buildNext

Builds a new test::user using the fragment after C<test/>.
For instance, if request resource is C<test/1/> , it will build
a Apache2::REST::Handler::test::user containing the user id C<1>

=cut

sub buildNext{
    my ( $self , $frag , $req ) = @_ ;
    
    my $subh = Apache2::REST::Handler::test::user->new($self) ;
    $subh->{'userid'} = $frag  ;
    return $subh ;
}

=head2 isAuth

Any method is allowed

=cut

sub isAuth{

lib/Apache2/REST/Overview.pod  view on Meta::CPAN

=head1 Apache2 REST Overview

=head2 Request life cycle.

The client performs a HTTP method on a resource uri.

L<Apache2::REST> splits the uri in fragments.

Apache2::REST builds a L<Apache2::REST::Handler> and let it handle the root fragment

Apache2::REST then writes the response back to the client with the appropriate writer.

If the response is written as a string (which is true for defaults writers),
this string is a unicode string encoded in UTF-8 bytes.

=head2 How a Apache2::REST::Handler works

If the requested resource is terminal, it performs the requested HTTP method (if allowed).

If the requested resource is not terminal, it solves the next fragment buy building
the next handler. By default, the next handler is a class one level down in the package
hierachy.

=head2 A request lifecycle example.

Client request: GET /foo/bar

URI fragments are C<(foo bar)>

A root handler is built according to Apache2RESTHandlerRootClass - See L<Apache2::REST>. Let's assume this root handler is C<MyApp::REST::API>. See L<Apache2::REST::Handler>.

This root handle is not terminal for this request, so it builds the next handler.

The next handler will be a MyApp::REST::API::foo

One more step and the terminal handler is a MyApp::REST::API::foo::bar

The method GET is called on the MyApp::REST::API::foo::bar instance.