Jerome Eteve > Apache2-REST > Apache2::REST



Annotate this POD


New  1
Open  0
View/Report Bugs
Module Version: 0.07   Source  


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


Version 0.07


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/
   LoadModule perl_module modules/

   # 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

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.


See the Google project page for wiki and collaborative tools:


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

Supported variables


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


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


Defines where to output the error in case of API error.

The default outputs the error in the response message and in the main apache2 error log.

Valid values are: 'both' (default) 'response' (outputs error only in response) 'server' (outputs error only in server logs. The response contains an error reference for easy retrieval in the error log file)


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)


    PerlSetVar Apache2RESTHandlerRootClass "MyApp::REST::API"


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


    PerlSetVar Apache2RESTParamEncoding "UTF-8"


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


    PerlSetVar Apache2RESTAppAuth "MyApp::REST::AppAuth"


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'
    header - With this method, the writer is selected from the MIME type given in the Accept HTTP header
             This MIME type should match one of the writer's mimeType.


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


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


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.


Jerome Eteve, <jerome at>

Scott Thoman, <scott dot thoman at steeleye dot com>


Please report any bugs or feature requests to

I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


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

    perldoc Apache2::REST

You can find the wiki with Cooking recipes and in depth articles at:


Copyright 2009-2010 The authors, all rights reserved.

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

syntax highlighting: