Apache2::REST - Micro framework for REST API implementation under apache2/mod_perl2/apreq2
Version 0.07
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 ;
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.
http://yourhost/
See Apache2::REST::Overview for more details about how it works.
See the Google project page for wiki and collaborative tools: http://code.google.com/p/apache2rest/
This mod_perl2 handler supports the following configurations (Via PerlSetVar):
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>
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)
http://localhost/test/
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.
fmt
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
xml
json
yaml
perl
bin
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.
MyApp::REST::Writer::mywriter
Apache2::REST::Writer
You can now use your new registered writer by using fmt=myfmt.
Jerome Eteve, <jerome at eteve.net>
<jerome at eteve.net>
Scott Thoman, <scott dot thoman at steeleye dot com>
<scott dot thoman at steeleye dot com>
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.
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
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Apache2-REST
CPAN Ratings
http://cpanratings.perl.org/d/Apache2-REST
Search CPAN
http://search.cpan.org/dist/Apache2-REST
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.
To install Apache2::REST, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Apache2::REST
CPAN shell
perl -MCPAN -e shell install Apache2::REST
For more information on module installation, please visit the detailed CPAN module installation guide.