The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
XAS-Service-0.01
River stage zero No dependents
++
/ XAS::Service::Resource

NAME

XAS::Service::Resource - Perl extension for the XAS environment

SYNOPSIS

 use Plack;
 use Template;
 use JSON::XS;
 use Plack::App;
 use Web::Machine;
 use XAS::Service::Server;
 use XAS::Service::Resource::Root;
 use Badger::Filesystem 'File';

 my $base = 'web';
 my $name = 'testing',
 my $description = 'test web service';

 sub build_app {
    my $self = shift;

    # define base, name and description

    my $base = $self->cfg->val('app', 'base', '/home/kevin/dev/XAS-Service/trunk/web');
    my $name = $self->cfg->val('app', 'name', 'WEB Services');
    my $description = $self->cfg->val('app', 'description', 'Test api using RESTFUL HAL-JSON');

    # Template config

    my $config = {
        INCLUDE_PATH => File($base, 'root')->path,   # or list ref
        INTERPOLATE  => 1,  # expand "$var" in plain text
    };

    # create various objects

    my $template = Template->new($config);
    my $json     = JSON::XS->new->utf8();

    # allow variables with preceeding _

    $Template::Stash::PRIVATE = undef;

    # handlers, using URLMap for routing

    my $builder = Plack::Builder->new();
    my $urlmap  = Plack::App::URLMap->new();
    
    $urlmap->mount('/' => Web::Machine->new(
        resource => 'XAS::Service::Resource',
        resource_args => [
            alias           => 'root',
            template        => $template,
            json            => $json,
            app_name        => $name,
            app_description => $description
        ] )
    );

    # static files

    $urlmap->mount('/js' => Plack::App::File->new(
        root => $base . '/root/js' )
    );

    $urlmap->mount('/css' => Plack::App::File->new(
        root => $base . '/root/css')
    );

    $urlmap->mount('/yaml' => Plack::App::File->new(
        root => $base . '/root/yaml/yaml')
    );

    return $builder->to_app($urlmap->to_app);

 }

 my $interface = XAS::Service::Server->new(
     -alias   => 'server',
     -port    => 9507,
     -address => 'localhost,
     -app     => $self->build_app(),
 );

 $interface->run();

DESCRIPTION

This module is a wrapper around Web::Machine::Resource. It provides the defaults that I have found useful when developing a REST based web service.

METHODS - Web::Machine

Web::Machine provides callbacks for processing the request. This are the ones that I have found useful to override.

init

This method interfaces the passed resource_args to accessors. It also pulls in the XAS environment and log handling.

is_authorized

This method uses basic authenication and checks wither the user is valid. This needs to be overridden.

options

Returns the allowed options for the service. This basically takes what is provided by allowed_methods(), content_types_provided(), content_types_accepted() and creates the proper headers for the response.

allowed_methods

This returns the allowed methods for the handler. The defaults are OPTIONS GET HEAD.

post_is_create

This method returns TRUE. This allows for processing based on content_types_provided() and content_types_accepted().

content_types_accepted

This method returns the accepted content types for this handler. This also allows processing based on those types. The defaults are:

 'application/json'                  which will call 'from_json'
 'application/x-www-form-urlencoded' which will call 'from_html'

content_types_provided

This method returns the content types that this handler will provided. This allows for processing based on those types. They defaults are:

 'text/html'            which will call 'to_html'
 'application/hal+json' which will call 'to_json'

charset_provided

This will return the accepted charset. The default is UTF-8.

finish_request

This method is called last and allows us to fix up error messages.

METHODS - Ours

These methods are used to make writting services easier.

get_navigation

This method returns a data structure used for navigation within the html interface. This needs to be overridden for any useful to happen.

This method returns the links associated with this handler. Used in the html interface and json responses. This needs to be overridden for anything useful to happen.

get_response

This method is called to help create a response. It calls get_navigation() and get_links() as helpers. It returns a data structure that will be converted to a html page or json depending on how the request was made. This needs to be overridden for anything useful to happen.

json_to_multivalue

This method will convert json parameters into a Hash::MultiValue object. This is to normalize the handling of posted data.

from_json

This methods converts the JSON post data into a Hash::MultiValue object and calls process_params().

to_json

This method is called when a json response is required.

from_html

This methods retrieves the post parameters and calls process_params().

to_html

This method is called when a html response is required.

from_json

This method is called when request is using json.

from_html

This method is called when a request is html.

format_json

Formats the response as json.

format_html

Formats the response as html.

process_params($params)

This method processes the post parameters. This needs to be overridden.

$params

The parameters that need to be processed.

ACCESSORS

These accessors are used to interface the arguments passed into the Web Machine Resource.

app_name

Returns the name of the service. Primarily used for the html interface.

app_description

Return the description of the service. Primarily used for the html interface.

json

Returns the handle for JSON::XS.

tt

Returns the handle for Template.

env

Returns the handle for the XAS environment.

log

Returns the handle for the XAS logging.

alias

Returns the alias for this handler. Used for logging purposes.

MUTATORS

errcode

Allows you to set an HTTP error code. Used for error handling.

errstr

Allows you to set an error string. Used for error handling.

SEE ALSO

Hash::MultiValue
Web::Machine::Resource
Web::Machine
XAS::Service
XAS

AUTHOR

Kevin L. Esteb, <kevin@kesteb.us>

COPYRIGHT AND LICENSE

Copyright (c) 2012-2016 Kevin L. Esteb

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0. For details, see the full text of the license at http://www.perlfoundation.org/artistic_license_2_0.