Apache2-REST
view release on metacpan or search on metacpan
--- #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
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");
}
( run in 1.333 second using v1.01-cache-2.11-cpan-df04353d9ac )