App::MREST::Dispatch - Resource handlers
Your application should not call any of the routines in this module directly. They are called by Web::MREST::Resource during the course of request processing. What your application can do is provide its own resource handlers.
The resource handlers are called as ordinary functions with a sole argument: the MREST context.
In this section we provide definitions of all resources handled by this module. These are picked up by Web::MREST::InitRouter.
This resource is the parent of all resources that do not specify a parent in their resource definition. EOH },
# bugreport 'bugreport' => { parent => '/', handler => { GET => 'handler_bugreport', }, cli => 'bugreport', description => 'Display instructions for reporting bugs in Web::MREST', documentation => <<'EOH', =pod
Returns a JSON structure containing instructions for reporting bugs. EOH },
# configinfo 'configinfo' => { parent => '/', handler => { GET => 'handler_configinfo', }, cli => 'configinfo', description => 'Display information about Web::MREST configuration', documentation => <<'EOH', =pod
Returns a list of directories that were scanned for configuration files. EOH },
# docu 'docu' => { parent => '/', handler => 'handler_noop', cli => 'docu', description => 'Access on-line documentation (via POST to appropriate subresource)', documentation => <<'EOH', =pod
This resource provides access to on-line documentation through its subresources: 'docu/pod', 'docu/html', and 'docu/text'.
To get documentation on a resource, send a POST reqeuest for one of these subresources, including the resource name in the request entity as a bare JSON string (i.e. in double quotes). EOH },
# docu/pod 'docu/pod' => { parent => 'docu', handler => { POST => 'handler_docu', }, cli => 'docu pod $RESOURCE', description => 'Display POD documentation of a resource', documentation => <<'EOH', =pod
This resource provides access to on-line help documentation in POD format. It expects to find a resource name (e.g. "employee/eid/:eid" including the double-quotes, and without leading or trailing slash) in the request body. It returns a string containing the POD source code of the resource documentation. EOH },
# docu/html 'docu/html' => { parent => 'docu', handler => { POST => 'handler_docu', }, cli => 'docu html $RESOURCE', description => 'Display HTML documentation of a resource', documentation => <<'EOH', =pod
This resource provides access to on-line help documentation. It expects to find a resource name (e.g. "employee/eid/:eid" including the double-quotes, and without leading or trailing slash) in the request body. It generates HTML from the resource documentation's POD source code. EOH },
# docu/text 'docu/text' => { parent => 'docu', handler => { POST => 'handler_docu', }, cli => 'docu text $RESOURCE', description => 'Display resource documentation in plain text', documentation => <<'EOH', =pod
This resource provides access to on-line help documentation. It expects to find a resource name (e.g. "employee/eid/:eid" including the double-quotes, and without leading or trailing slash) in the request body. It returns a plain text rendering of the POD source of the resource documentation. EOH },
# echo 'echo' => { parent => '/', handler => { POST => 'handler_echo', }, cli => 'echo [$JSON]', description => 'Echo the request body', documentation => <<'EOH', =pod
This resource simply takes whatever content body was sent and echoes it back in the response body. EOH },
# noop 'noop' => { parent => '/', handler => 'handler_noop', cli => 'noop', description => 'A resource that does nothing', documentation => <<'EOH', =pod
Regardless of anything, this resource does nothing at all. EOH },
# param/:type/:param 'param/:type/:param' => { parent => '/', handler => { 'GET' => 'handler_param', 'PUT' => 'handler_param', 'DELETE' => 'handler_param', }, cli => { 'GET' => 'param $TYPE $PARAM', 'PUT' => 'param $TYPE $PARAM $VALUE', 'DELETE' => 'param $TYPE $PARAM', }, description => { 'GET' => 'Display value of a meta/core/site parameter', 'PUT' => 'Set value of a parameter (meta only)', 'DELETE' => 'Delete a parameter (meta only)', }, documentation => <<'EOH', =pod
This resource can be used to look up (GET) meta, core, and site parameters, as well as to set (PUT) and delete (DELETE) meta parameters. EOH validations => { 'type' => qr/^(meta)|(core)|(site)$/, 'param' => qr/^[[:alnum:]_][[:alnum:]_-]+$/, }, },
# test/?:specs 'test/?:specs' => { parent => '/', handler => 'handler_test', cli => 'test [$SPECS]', description => "Resources for testing resource handling semantics", }, # version 'version' => { parent => '/', handler => { GET => 'handler_version', }, cli => 'version', description => 'Display application name and version', documentation => <<'EOH', =pod
Shows the software version running on the present instance. The version displayed is taken from the $VERSION package variable of the package specified in the MREST_APPLICATION_MODULE site parameter. EOH },
$VERSION
MREST_APPLICATION_MODULE
};
Initialize (populate) the router. Called from Resource.pm when the first request comes waltzing in.
Boilerplate code for use in handlers of resources that always exist
Handler for the bugreport resource.
bugreport
Handler for the configinfo resource.
configinfo
The definition of resource $docu_resource lacks a 'documentation' property EOH # if they want POD, give them POD; if they want HTML, give them HTML, etc. if ( $resource_name eq 'docu/pod' ) { $pl->{'format'} = 'POD'; $pl->{'documentation'} = $docs; } elsif ( $resource_name eq 'docu/html' ) { $pl->{'format'} = 'HTML'; $pl->{'documentation'} = pod_to_html( $docs ); } else { # fall back to plain text $pl->{'format'} = 'text'; $pl->{'documentation'} = pod_to_text( $docs ); } return $CELL->status_ok( 'MREST_DISPATCH_ONLINE_DOCUMENTATION', payload => $pl ); }
Echo request body back in the response
Handler for 'param/:type/:param' resource.
Generalized handler for resources that don't do anything.
The only purpose of this resource is testing/demonstration of request handling.
Handler for the version resource.
version
To install Web::MREST, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Web::MREST
CPAN shell
perl -MCPAN -e shell install Web::MREST
For more information on module installation, please visit the detailed CPAN module installation guide.