The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Web-DataService-0.13
River stage zero No dependents
++
/ Web::DataService::Configuration

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:

  1. The sub-service will inherit the parent's attributes.

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

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.