NAME
Web::DataService::Configuration - configuration attributes and how to use them
SYNOPSIS
This document lists the various attributes available for you to use in configuring a data service with Web::DataService.
ATTRIBUTE SYNTAX
The various configuration methods provided by Web::DataService all use a consistent syntax. Some of these routines take an initial name parameter; all of the rest of the parameters must be a mixture of hashrefs and strings. The hashrefs each configure some object, and the strings each document the object that they follow. We refer to this mix of attribute hashrefs and documentation strings as a definition list.
$ds->define_format(
{ name => 'json', content_type => 'application/json',
doc_path => 'formats/json', title => 'JSON',
default_vocab => 'com' },
"The JSON format is intended primarily to support client applications,",
"including the PBDB Navigator. Response fields are named using compact",
"3-character field names.",
{ name => 'xml', disabled => 1, content_type => 'text/xml', title => 'XML',
doc_path => 'formats/xml',
default_vocab => 'dwc' },
"The XML format is intended primarily to support data interchange with",
"other databases, using the Darwin Core element set.");For example, the above call defines two output formats: one named 'json' and the other named 'xml'. Each of these objects is defined by the set of attributes contained in a hashref. All of the documentation strings are automatically collected (joined by newlines) as the attribute "doc" of the object whose definition they immediately follow.
ATTRIBUTE DOCUMENTATION
Data Service attributes
You can specify any of the following attributes when defining a new data service or sub-service. The attribute name is always required, the others are optional. Default values, if any, are specified in each entry.
name
Provides a unique identifier for this data service.
label
Provides a short title by which this data service can be referred to in documentation.
title
Provides a long title by which this data service can be referred to in documentation.
parent
The value of this attribute, if specified, must be a reference to an instance of Web::DataService. The newly defined instance will be a sub-service of that instance. This means that:
The sub-service will inherit the parent's attributes.
A new request generated on the parent data service may be assigned to the child, based on the path prefixes.
version
If specified, this will be reported in the standard documentation template as part of the header. You can increment this whenever you make a change to the interface. The value can be any string, i.e. "23" or "1.2b5".
default_limit
This sets the default limit on the number of results reported for any request that does not itslef specify a limit. If not set, it defaults to 500.
streaming_threshold
This sets the threshold for streaming. Any request whose (serialized) result exceeds this size in bytes will be streamed, provided that streaming is available.
allow_unrecognized
If this attribute is given a true value, then unrecognized parameter names will generate warnings instead of errors. See HTTP::Validate.
foundation_plugin
This value of this attribute, if specified, must be the name of a module that implements the Web::DataService foundation_plugin interface (see Web::DataService::Plugins). This plugin handles the basic functionality of parsing and generating HTTP requests and interacting with the HTTP server. You only need to specify this attribute if you wish to use a custom plugin; if Dancer is already loaded, then this attribute will default to Web::DataService::Plugin::Dancer.
use Dancer;
use Web::Dataservice;
my $ds = Web::DataService->new({ name => 'myserv' });If you set up your code like the above example, the right plugin will be loaded by default. If no foundation plugin can be loaded, the call to new will die.
templating_plugin
The value of this attribute, if specified, must be the name of a module that implements the Web::DataService templating_plugin interface (see Web::DataService::Plugins). If Template is already loaded, then this attribute will default to Web::DataService::Plugin::Template.
It is possible to define a data service without a templating plugin. However, in this case auto-documentation will not be enabled.
backend_plugin
The value of this attribute, if specified, must be the name of a module that implements the Web::DataService backend_plugin interface (see Web::DataService::Plugins). This currently includes a single method, get_connection, which returns a database connection handle. If Dancer::Plugin::Database is already loaded, then this attribute will default to Web::DataService::Plugin::Dancer.
It is possible to define a data service without a backend plugin, you simply have to implement a different method for obtaining a backend connection.
path_prefix
The value of this attribute must be a string. It should be the common prefix of the URL paths for this data service. If you define multiple sub-services, the path prefixes will be used to select which sub-service should handle each request.
ruleset_prefix
The value of this attribute must be a string. It will be added to the front of each auto-generated ruleset name.
public_access
If this attribute is given a true value, then each HTTP response will include the header "Access-Control-Allow-Origin: *".
doc_templates
The value of this attribute must be a file path indicating where the templates for documentation pages are stored. Relative paths are evaluated relative to the current directory of the data service process. If not specified, this attribute defaults to "doc".
doc_defs
The value of this attribute must be the name of a template file in the documentation template directory. It will be included before every documentation template that gets rendered. The idea is for this template to define functions/directives that can be used by the documentation templates. However, you can use it in any way that you choose.
doc_header
The value of this attribute must be the name of a template file in the documentation template directory. For each documentation template that gets rendered, this file will be included after the definition file and before the documentation template. The idea is for this to output the header for the documentation pages, but you can use it in any way that you choose.
doc_footer
The value of this attribute must be the name of a template file in the documentation template directory. For each documentation template that gets rendered, this file will be included after the definition file and before the documentation template. The idea is for this to output the header for the documentation pages, but you can use it in any way that you choose.
Path attributes
You can specify any of the following attributes when configuring a new path node. The attribute "path" is required, the rest are optional. Path attributes inherit hierarchically. Any path whose attributes include both "class" and "method" indicates a data service operation. Any path whose attributes include "doc_title" indicates a documentation page. The special path "/" defines a root set of attributes which are inherited by all other path nodes associated with this data service.
path
This required attribute specifies the path to which the other attributes apply. Attributes inherit hierarchically, so that a node whose path is "foo/bar" inherits all the attributes of "foo" except for those which are specifically overridden.
class
This attribute specifies the name of a class into which any request generated on this path will be blessed. That class must itself be set up to inherit from Web::DataService::Request. Any path which will correspond to a data service operation must have a valid value for this attribute.
method
This attribute specifies a method which will be called at the appropriate time in order to execute the data service operation. Any path which will correspond to a data service operation must have a valid value for this attribute.
arg
The value of this attribute, if any, will be passed as an argument to the operation method. This can be used to distinguish between different paths which may call the same method.
ruleset
If this attribute is specified, then the correspondingly named ruleset will be called to validate and clean the parameter values for any request on this path. If not specified, a ruleset name will be automatically generated using the ruleset prefix (if any) defined for this data service followed by the path with slashes "/" replaced by colons ":". This automatically generated ruleset will be used if a ruleset with that name is actually defined. If no ruleset could be found, then only the raw parameter values will be available and no checking of parameter values will occur.
output
If this attribute is specified, then the correspondingly named output block will be used to generate result messages according to the selected output format.
You may specify a value for this attribute and for "output_opt" for the same path, in which case the former specifies the fixed output for the operation and the latter specifies additional optional output.
If the value of this attribute does not correspond to any named output block, then an error will be generated at runtime.
output_opt
If this attribute is specified, then the correspondingly named output map (set) will be used to select optional output blocks according to the value of the parameter named by "output_param".
public_access
output_param
vocab_param
limit_param
offset_param
count_param
nohead_param
linebreak_param
showsource_param
textresult_param
send_files
file_dir
default_limit
streaming_threshold
init_operation_hook
post_params_hook
post_configure_hook
post_process_hook
output_record_hook
allow_method
allow_format
allow_vocab
doc_template
doc_header
doc_defs
doc_footer
doc_title
Format attributes
Vocabulary attributes
Set element attributes
Output element attributes
AUTHOR
mmcclenn "at" cpan.org
BUGS
Please report any bugs or feature requests to bug-web-dataservice at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Web-DataService. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
COPYRIGHT & LICENSE
Copyright 2014 Michael McClennen, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.