The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Dancer-Plugin-RPC-RESTISH-1.01
River stage zero No dependents
/ Dancer::Plugin::RPC::RESTISH

NAME

Dancer::Plugin::RPC::RESTISH - Simple plugin to implement a restish interface.

SYNOPSIS

In the Controler-bit:

    use Dancer::Plugin::RPC::RESTISH;
    restish '/endpoint' => {
        publish           => 'pod',
        arguments         => ['MyProject::Admin'],
        cors_allow_origin => '*',
    };

and in the Model-bit (MyProject::Admin):

    package MyProject::Admin;
    
    =for restish GET@ability/:id rpc_get_ability_details
    
    =cut
    
    sub rpc_get_ability_details {
        my %args = @_; # contains: {"id": 42}
        return {
            # datastructure
        };
    }
    1;

DESCRIPTION

RESTISH is an implementation of REST that lets you bind routes to code in the style the rest of Dancer::Plugin::RPC modules do. One must realise that this basically binds REST-paths to RPC-methods (that's not ideal, but saves a lot of code).

This version only supports JSON as data serialisation.

restish '/base_path' => \%publisher_arguments

See Dancer::Plugin::RPC, Dancer::Plugin::RPC::JSONRPC, Dancer::Plugin::RPC::RESTRPC, Dancer::Plugin::RPC::XMLRPC for more information about the %publisher_arguments.

Implement the routes for RESTISH

The plugin registers Dancer-any route-handlers for the base_path + method_path and the route-handler looks for a data-handler that matches the path and HTTP-method.

Method-paths can contain colon-prefixed parameters native to Dancer. These parameters will be merged with the content-parameters and the query-parameters into a single hash which will be passed to the code as the parameters.

Method-paths are prefixed by a HTTP-method followed by @:

publisher => 'config'

plugins: 'RPC::RESTISH': '/rest': 'MyProject::Admin': 'GET@resources': 'get_all_resourses' 'POST@resource': 'create_resource' 'GET@resource/:id': 'get_resource' 'PATCH@resource/:id': 'update_resource' 'DELETE@resource/:id': 'delete_resource'

publisher => 'pod'
    =for restish GET@resources       get_all_resources /rest
    =for restish POST@resource       create_resource   /rest
    =for restish GET@resource/:id    get_resource      /rest
    =for restish PATCH@resource/:id  update_resource   /rest
    =for restish DELETE@resource/:id delete_resource   /rest

The third argument (the base_path) is optional.

The plugin for RESTISH also adds 2 fields to $Dancer::RPCPlugin::ROUTE_INFO:

        local $Dancer::RPCPlugin::ROUTE_INFO = {
            plugin        => PLUGIN_NAME,
            endpoint      => $endpoint,
            rpc_method    => $method_name,
            full_path     => request->path,
            http_method   => $http_method,
            # These two are added
            route_matched => $found_match,      # PATCH@resource/:id
            matched_re    => $match_re,         # PATCH@resource/[^/]+
        };

CORS (Cross-Origin Resource Sharing)

If one wants the service to be directly called from javascript in a browser, one has to consider CORS as browsers enforce that. This means that the actual request is preceded by what's called a preflight request that uses the HTTP-method OPTIONS with a number of header-fields.

Origin
Access-Control-Request-Method

The plugin supports considering these CORS requests, by special casing these OPTIONS requests and always sending the Access-Control-Allow-Origin header as set in the config options.

cors_allow_origin => $list_of_urls | '*'

If left out, no attempt to honour a CORS OPTIONS request will be done and the request will be passed.

When set to a value, the OPTIONS request will be executed, for any http-method in the Access-Control-Request-Method header. The response to the OPTIONS request will also contain every Access-Control-Allow-* header that was requested as Access-Control-Request-* header.

When set, all responses will contain the Access-Control-Allow-Origin-header with either * if that was set, or the value of the actual Origin-header that was passed and equals one the preset values.

INTERNAL

build_dispatcher_from_config

Creates a (partial) dispatch table from data passed from the (YAML)-config file.

build_dispatcher_from_pod

Creates a (partial) dispatch table from data provided in POD.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See:

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

COPYRIGHT

(c) MMXX - Abe Timmerman <abeltje@cpan.org>