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

NAME

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

VERSION

Version 0.07

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>

Apache2RESTErrorOutput

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)

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'
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

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.

AUTHORS

Jerome Eteve, <jerome at eteve.net>

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

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