--- name: "Web::MREST::Dispatch" section: "3pm" platform: "linux" package: "libweb-mrest-perl" version: "0.290-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Web::MREST::Dispatch" --- # Web::MREST::Dispatch(3pm) Resource handlers ## NAME App::MREST::Dispatch - Resource handlers ## DESCRIPTION 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. ## INITIALIZATION/RESOURCE DEFINITIONS 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\ }, ``` }; ``` ## FUNCTIONS ### init\_router Initialize (populate) the router. Called from Resource.pm when the first request comes waltzing in. ### \_first\_pass\_always\_exists Boilerplate code for use in handlers of resources that always exist ### handler\_bugreport Handler for the `"bugreport"` resource. ### handler\_configinfo Handler for the `"configinfo"` resource. ### handler\_docu 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` ); } ### handler\_echo Echo request body back in the response ### handler\_param Handler for 'param/:type/:param' resource. ### handler\_noop Generalized handler for resources that don't do anything. ### handler\_test The only purpose of this resource is testing/demonstration of request handling. ### handler\_version Handler for the `"version"` resource.