Apache2-REST

 view release on metacpan or  search on metacpan

META.yml  view on Meta::CPAN

--- #YAML:1.0
name:                Apache2-REST
version:             0.07
abstract:            Micro framework for REST API implementation under apache2/mod_perl2/apreq2
license:             ~
author:              
    - Jerome Eteve <jerome@eteve.net>
generated_by:        ExtUtils::MakeMaker version 6.42
distribution_type:   module
requires:     
    Apache2::Log:                  2.000001
    Apache2::Request:              2.08
    Class::AutoAccess:             0.02
    Digest::MD5:                   2.33

README  view on Meta::CPAN

Apache2-REST

This module provides a framework for quick and easy implementation of a RESTful API under apache2/mod_perl2/apreq2

Dependencies are listed in Makefile.PL.

INSTALLATION

To install this module, run the following commands:

    perl Makefile.PL
    make
    make test

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

use Apache2::REST::Request ;

use Apache2::REST::Conf ;

use Data::Dumper ;

our $VERSION = '0.07';

=head1 NAME

Apache2::REST - Micro framework for REST API implementation under apache2/mod_perl2/apreq2

=head1 VERSION

Version 0.07

=head1 QUICK TUTORIAL

=head2 1. Implement a Apache2::REST::Handler

This module will handle the root resource of your REST API.

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

Apache2::REST::AppAuth - Base class for application authentication

=cut


=head2 new

Returns a new instance of this class.

If you override this, remember it is called without
arguments by the framework.


=cut

sub new{
    my ( $class ) = @_ ;
    return bless {} , $class ;
}

=head2 init

Override this if you want to initialise this plugin
with properties accessible through the Apache2::Request 

Called by the framework like this:

    $this->init($req) ;

=cut

sub init{
    my ( $self , $req ) = @_ ;
    # Nothing by default
}

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

=head2 authorize

Implement this to let the Application authentifier
decide if the application can access the API or not.

Please set resp->status() and resp->message() ;

Returns true if authorized. False otherwise.

Called like this by the framework:

$this->authorize($req , $resp ) ;

=cut

sub authorize{
    my ( $self , $req , $resp ) = @_ ;
    return 1 ;
}

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

=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) ;

$request is an Apache2::REST::Request (which is a subclass of Apache2::Request).
$response is an Apache2::REST::Response 


Each method must return a valid Apache2::Const::HTTP_* code. 
Typically Apache2::Const::HTTP_OK when everything went smoothly.

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

=cut

sub class{
    my ( $self ) = @ _;
    return ref $self || $self ;
}

=head2 handle

Handles a request and does the framework magic.
Override at your own risks.

=cut

sub handle{
    my ( $self , $stack , $req , $resp ) = @_ ;
    #warn "Handling ".Dumper($stack)."\n" ;
    if ( 0 == @$stack ){
        my $method = $req->method();
        ## Check auth first

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

=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.

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

=head2 isAuth

Given a method and a request, returns true if this method is allowed.

The default implementation delegates to the parent.

Nothing is allowed by default. So you need to override this method at least once.

It is called by the framework like this (for instance):

$this->isAuth('GET' , $req) ;

=cut

sub isAuth{
    my ( $self , $method , $req  ) = @ _;
    if ( $self->parent()){
        return $self->parent()->isAuth($method , $req ) || 0 ;
    }

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

sub new{
    my ( $class ) = @_;
    return bless {} , $class;
}


=head2 mimeType

Returns the mime type this writer will output.

It is called like this by the framework:

   $this->mimeType($resp) ;

So you can adapt the mime type according to the response to be given.

=cut

sub mimeType{
    my ( $self , $resp )=@_;
    return '' ;
}

=head2 asBytes

Returns the bytes the framework has to write back to client.

It is called by the framework like this ($resp is a Apache2::REST::Response):

    $this->asBytes($resp) ;

=cut

sub asBytes{
    my ($self,  $resp ) = @_ ;
    return '' ;
}

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

    return bless { xml_simple => XML::Simple->new() } , $class;
}

=head2 mimeType

Getter

=cut

sub mimeType{
    return 'application/xml' ; ## The framework requires this to be unique per writer type.
}

=head2 getPreambleBytes

Returns the response as xml UTF8 bytes for output.

=cut

sub getPreambleBytes{
    my ($self,  $resp ) = @_ ;

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

sub new{
    my ( $class ) = @_;
    return bless {} , $class;
}


=head2 mimeType

Returns the mime type this writer will output.

It is called like this by the framework:

   $this->mimeType($resp) ;

This defaults to multipart/x-mixed-replace (makes it easy to test in the browser)
but can be overridden.  For example, one might want to use plain
multipart/mixed.

=cut

sub mimeType{
    my ( $self , $resp )=@_;
    return 'multipart/x-mixed-replace';
}

=head2 getPreambleBytes

Returns the bytes the framework has to write back to client as a Stream preamble.
This defaults to "" for the multipart writer since data typically isn't
send with the initial response (it doesn't really have a formal mime type at
that point).  Normally the first relevant content is the first "part" which
comes with it's own headers.

It is called by the framework like this ($resp is a Apache2::REST::Response):

    $this->getPreambleBytes($resp) ;

=cut

sub getPreambleBytes{
    my ($self,  $resp ) = @_ ;
    return Encode::encode_utf8("");
}


=head2 getNextPart

Returns the next part of the multipart response, or undef at the end of the stream.
The chunk should be a hash containing 'mimetype' and 'data'.  This allows
the subclass to dictate the mimetype of every chunk and, thus, they
can all be different if desired (an xml doc, then an audio file for ex.).

Called by the framework like that:

while( defined my $chunk = $this->getNextChunk($response) ){
    my $mimetype = $chunk->{'mimetype'};
    my $bytes    = $chunk->{'data'};
  ...
}

=cut

sub getNextPart{

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

    confess("Please implement me in an application subclass");
}

=head2 getPostambleBytes

Returns the last bytes to write in the stream when the stream is finished.
This defaults to "" for the multipart writer and probably shouldn't be
changed since it would sandwhich data between the final chunk and the final
boundary string.

Called by the framework like that:

$this->getPostambleBytes($response);

=cut

sub getPostambleBytes{
    my ($self, $resp) = @_;
    return Encode::encode_utf8("");
}

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

sub new{
    my ( $class ) = @_;
    return bless {} , $class;
}


=head2 mimeType

Returns the mime type this writer will output.

It is called like this by the framework:

   $this->mimeType($resp) ;

So you can adapt the mime type according to the response to be given.

=cut

sub mimeType{
    my ( $self , $resp )=@_;
    confess("Please implement me in an application subclass");
}

=head2 getPreambleBytes

Returns the bytes the framework has to write back to client as a Stream preamble.

It is called by the framework like this ($resp is a Apache2::REST::Response):

    $this->getPreambleBytes($resp) ;

=cut

sub getPreambleBytes{
    my ($self,  $resp ) = @_ ;
    confess("Please implement me in an application subclass");
}


=head2 getNextBytes

Returns the next bytes of the stream, or undef at the end of the stream.

Called by the framework like that:

while( defined my $bytes = $this->getNextBytes($response) ){
  ...
}

=cut

sub getNextBytes{
    my ($self, $resp) = @_;
    confess("Please implement me in an application subclass");
}

=head2 getPostambleBytes

Returns the last bytes to write in the stream when the stream is finished.

Called by the framework like that:

$this->getPostambleBytes($response);

=cut

sub getPostambleBytes{
    my ($self, $resp) = @_;
    confess("Please implement me in an application subclass");
}