NAME
Web::DataService - a framework for building data service applications for the Web
VERSION
Version 0.10
SYNOPSIS
This module provides a framework for you to use in building data service applications for the World Wide Web. Such applications sit between a data storage and retrieval system on one hand and the Web on the other, and fulfill HTTP-based data requests by fetching the appropriate data from the backend and expressing it in an output format such as JSON or XML.
Using the methods provided by this module, you start by defining a set of output formats, output blocks, vocabularies, and parameter rules, followed by a set of data service operations. Each of these objects is configured by a set of attributes, optionally including documentation strings.
You continue by writing one or more classes whose methods will handle the "meat" of each operation: constructing one or more queries on the backend data system and fetching the resulting data. This module then handles the rest of the work necessary for handling each data service request, including serializing the result in the appropriate output format.
METHODS
CONFIGURATION
The following methods are used to configure a web data service application.
new ( { attributes ... } )
Defines a new data service instance. This is generally the first step in configuring a web dataservice application. The available attributes are described in Web::DataService::Attributes. The attribute name is required; the others are optional, and may be specified in the application configuration file instead. See Web::DataService::Intro for instructions on how to set up an application.
define_subservice ( { attributes ... } )
Defines a new data service instance that will be a sub-service of the base instance. You can use this method if you wish to have multiple versions of your service available, i.e a development version and a stable version. The sub-service will inherit all of the attributes of the parent, except those which are explicitly specified.
define_vocab ( { attributes ... }, documentation ... )
Defines one or more vocabularies, using the specified attributes and documentation strings.
valid_vocab ( )
Returns a code reference which can be used in a parameter rule to accept only valid vocabulary names.
define_format ( { attributes ... }, documentation ... )
Defines one or more formats, using the specified attributes and documentation strings.
define_path ( { attributes ... } )
Defines a new path, using the specified attributes. Paths do not (currently) have associated documentation strings.
define_ruleset ( ruleset_name, { attributes ... }, documentation ... )
Define a ruleset with the given name, containing the specified rules and documentation. The arguments to this method are simply passed on to the define_ruleset method of HTTP::Validate.
EXECUTION
The following methods are available for you to use in the part of your code that handles incoming requests.
new_request ( outer, path )
Returns an object from the class Web::DataService::Request, representing a request on the specified path. This request can then be executed (using the execute method) which, in most cases, is all that is necessary to completely handle a request.
The parameter outer should be a reference to the object generated by the underlying Web Application Framework (i.e. Dancer) to represent this request. The parameter path should be the path corresponding to the requested operation.
If the data service instance on which you call this method has defined sub-services, the appropriate sub-service will be automatically selected.
set_mode ( mode ... )
Turns on one or more of the following modes.
- debug
-
Produces additional debugging output to STDERR.
- one_request
-
Configures the data service to satisfy one request and then exit. This is generally used for testing purposes.
get_attr ( attribute )
Returns the value of the specified data service attribute.
get_path_attr ( path, attribute )
Returns the specified attribute of the specified path, if the specified path and attribute are both defined. Return undefined otherwise. You can use this to test whether a particular path is in fact defined.
get_connection ( )
If a backend plugin is available, obtains a connection handle from it. You can use this method when initializing your data classes.
get_config ( )
Returns a hash of configuration values from the application configuration file.
DOCUMENTATION
The following methods are available for you to use in generating documentation. If you use the included documentation templates, you will probably not need to call them directly.
document_vocab ( path, { options ... } )
Return a documentation string in POD for the vocabularies that are allowed for the specified path. The optional options hash may include the following:
- all
-
Document all vocabularies, not just those allowed for the path.
- extended
-
Include the documentation string for each voabulary.
document_formats ( path, { options ... } )
Return a string containing documentation in POD for the formats that are allowed for the specified path. The optional options hash may include the following:
- all
-
Documents all formats, not just those allowed for the path.
- extended
-
Includes the documentation string for each format.
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.