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

NAME

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

VERSION

Version 0.04

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 the Apache2::REST::Handler manpage for about how to implement a handler.

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

See the Apache2::REST::Overview manpage 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 the Apache2::REST::AppAuth manpage 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'
    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.

Example:


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

=head3 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 the REST::Client manpage

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

http://code.google.com/p/apache2rest/issues/list

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

SUPPORT

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:

http://code.google.com/p/apache2rest/w/list

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.

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