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.
get_links
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.
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
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.