/ 
Apache2-REST-0.03
River stage zero No dependents
/ Apache2::REST

NAME

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

VERSION

Version 0.03

QUICK TUTORIAL

1. Implement a Apache2::REST::Handler

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

package MyApp::REST::API ;
use warnings ;
use strict ;
 
# Implement the GET HTTP method.
sub GET{
    my ($self, $request, $response) = @_ ;
    $response->data()->{'api_mess'} = 'Hello, this is MyApp REST API' ;
    return Apache2::Const::HTTP_OK ;
}
# Authorize the GET method.
sub isAuth{
   my ($self, $method, $req) = @ _; 
   return $method eq 'GET';
}
1 ;

2. Configure apache2

Apache2::REST is a mod_perl2 handler.

In your apache configuration:

# Make sure you
LoadModule apreq_module modules/mod_apreq2.so
LoadModule perl_module modules/mod_perl.so

# Load Apache2::REST
PerlModule Apache2::REST 
# Let Apache2::REST handle the /
# and set the root handler of the API
<Location />
   SetHandler perl-script
   PerlSetVar Apache2RESTHandlerRootClass "MyApp::REST::API"
   PerlResponseHandler  Apache2::REST
</Location>

See Apache2::REST::Handler for about how to implement a handler.

Then access http://yourhost/. You should see your greeting message from your MyApp::REST::API handler.

See Apache2::REST::Overview for more details about how it works.

PARTICIPATE

See the Google project page for wiki and collaborative tools: http://code.google.com/p/apache2rest/

CONFIGURATION

This mod_perl2 handler supports the following configurations (Via PerlSetVar):

Supported variables

Apache2RESTAPIBase

The base of the API application. If ommitted, / is assumed. Use this to implement your API as a sub directory of your server.

Example:

<Location /api/>
  ...
  PerlSetVar Apache2RESTAPIBase "/api/" ;
</Location>

Apache2RESTHandlerRootClass

root class of your API implementation. If ommitted, this module will feature the demo implementation Accessible at http://localhost/test/ (providing you installed this at the root of the server)

Example:

PerlSetVar Apache2RESTHandlerRootClass "MyApp::REST::API"

Apache2RESTParamEncoding

Encoding of the parameters sent to this API. Default is UTF-8. Must be a value compatible with Encode

Example:

PerlSetVar Apache2RESTParamEncoding "UTF-8"

Apache2RESTAppAuth

Specifies the module to use for application authentication. See Apache2::REST::AppAuth for API.

Example:

PerlSetVar Apache2RESTAppAuth "MyApp::REST::AppAuth"

Apache2RESTWriterSelectMethod

Use this to specify the writer selection method. If not specifid the writer is selected using the fmt parameter.

Valid values are:

param (the default) - With this method, the writer is selected from the fmt parameter. For instance '?fmt=json'
extension - With this method, the writer is selected from the url extension. For instance : '/test.json'

Example:

When using 'param' (default) ask for json format like this: http://localhost/test/?fmt=json
When using 'extension' : http://localhost/test.json

Apache2RESTWriterDefault

Sets the default writer. If ommitted, the default is xml. Available writers are xml, json, yaml, perl, bin

command line REST client

This module comes with a commandline REST client to test your API:

$ restclient
usage: restclient -r <resource URL> [ -m <http method> ] [ -p <http paramstring> ] [ -h <http headers(param syntax)> ]

It is written as a thin layer on top of REST::Client

Apache2RESTWriterRegistry

Use this to register your own Writer Classes.

For instance, you want to register your writer under the format name myfmt:

PerlAddVar Apache2RESTWriterRegistry 'myfmt'
PerlAddVar Apache2RESTWriterRegistry 'MyApp::REST::Writer::mywriter"

MyApp::REST::Writer::mywriter Must be a subclass of Apache2::REST::Writer.

You can now use your new registered writer by using fmt=myfmt.

AUTHOR

Jerome Eteve, <jerome at eteve.net>

BUGS

Please report any bugs or feature requests to bug-apache2-rest at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Apache2-REST. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Apache2::REST

COPYRIGHT & LICENSE

Copyright 2009 Careerjet Ltd, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.