view release on metacpan or  search on metacpan

lib/CGI/Application/Plugin/REST.pm  view on Meta::CPAN

the HTTP method (all upper case and all lower case respectively) to a run mode
that is determined by a dispatch rule which provides a limited version of
L<C::A::P::REST|CGI::Application::Plugin::REST>'s L<rest_resource|rest_resource()> function.

=head2 L<C::A::P::ActionDispatch|CGI::Application::Plugin::ActionDispatch>

This module adds an attribute handler to run modes of your choice which enable
parsing of the path info with regular expressions and dispatch to the run mode
matched. Capturing parentheses in the regex can be accessed via the
C<action_args()> method.

Dispatch based on HTTP method or MIME media type is not supported.

=head2 L<C::A::P::Routes|CGI::Application::Plugin::Routes>

This module installs a prerun hook that matches path info segments with support
for capturing variable with the : ? and * tokens.  They are retrievable in run
modes as L<CGI|CGI> parameters (i.e. via C<$self-E<gt>query-E<gt>param()>

Dispatch based on HTTP method or MIME media type is not supported.

=head1 DIAGNOSTICS

During the dispatch process, errors can occur in certain circumstances. If an
error occurs the appropriate HTTP status is set and execution passes to the
run mode set by L<rest_error_mode|rest_error_mode()>.  Here is a list of status codes and
messages.

=over 4

=item * 404 No Route Found

None of the specified routes matched the request URI.

=item * 405 Method '$method' Not Allowed

The route you specified with L<rest_route|rest_route()> does not allow this HTTP
request method.  An HTTP C<Allow> header is added to the response specifying
which methods can be used.

=item * 415 Unsupported Media Type

None of the MIME media types requested by the client can be returned by this
route and there is no handler for C<*/*>.

=item * 500 No Dispatch Table

This error can occur if L<rest_route|rest_route()> was not called.

=item * 500 Application Error

The function that was called for this run_mode C<die>'d somewhere.

=item * 501 Function '$function_name' Doesn't Exist

The function that you wanted to call from L<rest_route|rest_route()> for this run_mode
doesn't exist in your application.

=back

=head1 BUGS AND LIMITATIONS

There are no known problems with this module.

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

=head1 SEE ALSO

=over 4

=item * L<CGI::Application|CGI::Application>:

The application framework this module plugs into.

=item * L<REST::Utils|REST::Utils>:

L<C::A::P::REST|CGI::Application::Plugin::REST> uses my L<REST::Utils|REST::Utils> module behind the
scenes.

=item * L<REST::Application|REST::Application>:

This module by Matthew O'Connor gave me some good ideas.

=item * L<http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm>:

Roy Fieldings' doctoral thesis in which the term REST was first defined.

=item * L<http://www.xml.com/pub/at/34>

"The Restful Web" columns by Joe Gregorio have been very useful to me in
understanding the ins and outs of REST.

=back

=head1 THANKS

Much of the code in this module is based on L<C::A::P::Routes|CGI::Application::Plugin:Routes>
by JuliE<aacute>n Porta who in turn credits Michael Peter's L<CGI::Application::Dispatch|CGI::Application::Dispatch>.

=head1 AUTHOR

Jaldhar H. Vyas, C<< <jaldhar at braincells.com> >>

=head1 LICENSE AND COPYRIGHT

Copyright (c) 2010 Consolidated Braincells Inc., all rights reserved.

This distribution is free software; you can redistribute it and/or modify it
under the terms of either:

a) the GNU General Public License as published by the Free Software
Foundation; either version 2, or (at your option) any later version, or

b) the Artistic License version 2.0.

The full text of the license can be found in the LICENSE file included
with this distribution.