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