NAME
Web::DataService - a framework for building data service applications for the Web
VERSION
Version 0.23
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. Each valid request is handled by fetching or storing the appropriate data using the backend data system and serializing the output in a format such as JSON, CSV, or XML.
Using the methods provided by this module, you start by defining a set of data service elements: output formats, output blocks, vocabularies, and parameter rules, followed by a set of data service nodes representing the various operations to be provided by your service. Each of these objects is configured by a set of attributes, optionally including documentation strings. You continue by writing one or more modules whose methods will carry out the core part of each data service operation: talking to the backend data system to fetch and/or store the relevant data, based on the parameter values provided in a data service request.
The Web::DataService code then takes care of most of the work necessary for handling each request, including checking the parameter values, determining the response format, calling your operation method at the appropriate time, and serializing the result. It also generates appropriate error messages when necessary. Finally, it auto-generates documentation pages for each operation based on the elements you have defined, so that your data service is always fully and correctly documented.
A Web::DataService application is built on top of a "foundation framework" that provides the basic functionality of parsing HTTP requests and constructing responses. At the present time, the only one that can be used is Dancer. However, we plan to add compatibility with other frameworks such as Mojolicious and Catalyst soon.
MORE DOCUMENTATION
This documentation describes the methods of class Web::DataService. If you want a detailed description of this module and its reasons for existence, look at Web::DataService::Introduction. See Web::DataService::Tutorial for a step-by-step guide to the example application included with this distribution. For a detailed description of how to configure a data service using this framework, see Web::DataService::Configuration. Finally, for an overview of the elements used in the documentation templates, see Web::DataService::Documentation.
METHODS
CONSTRUCTOR
new ( { attributes ... } )
This class method defines a new data service instance. Calling it is generally the first step in configuring a data service application. The available attributes are described in ""Data service instantiation:" in Web::DataService::Configuration. The attribute name is required; the others are optional, and some of them may be specified in the application configuration file instead.
Once you have a data service instance, the next step is to configure it by adding various data service elements. This is done by calling the methods listed below.
CONFIGURATION
The following methods are used to configure a data service application. For a list of the available attributes for each method, and an overview of the calling convention, see Web::DataService::Configuration. For detailed instructions on how to set up a data service application, see Web::DataService::Tutorial.
set_foundation ( module_name )
You can call this as a class method if you wish to use a custom foundation framework. The argument must be the module name, which will be require'd. This call must occur before any data services are defined.
define_vocab ( { attributes ... }, documentation ... )
Defines one or more vocabularies, using the specified attributes and documentation strings. Each vocabulary represents a different set of terms by which to label and express the returned data.
define_format ( { attributes ... }, documentation ... )
Defines one or more response formats, using the specified attributes and documentation strings. Each of these formats represents a configuration of one of the available serialization modules.
define_node ( { attributes ... }, documentation ... )
Defines one or more data service nodes, using the specified attributes and documentation strings. Each of these nodes represents either an operation provided by the data service or a page of documentation.
define_block ( block_name, { attributes ... }, documentation ... )
Defines an output block with the given name, containing the specified output fields and documentation.
define_set ( set_name, { attributes ... }, documentation ... )
Defines a named set of values, possibly with a mapping to some other list of values. These can be used to specify the acceptable values for request parameters, to translate data values into different vocabularies, or to specify optional output blocks.
define_ruleset ( ruleset_name, { attributes ... }, documentation ... )
Defines a ruleset with the given name, containing the specified rules and documentation. These are used to validate parameter values.
EXECUTION
The following methods are available for you to use in the part of your code that handles incoming requests. This will typically be inside one or more "route handlers" or "controllers" defined using the foundation framework.
handle_request ( outer, [ attrs ] )
A call to this method directs the Web::DataService framework to handle the current request. Depending on how your application is configured, one of the data service operation methods that you have written may be called as part of this process.
You may call this either as a class method or an instance method. In the former case, if you have defined more than one data service instance, the method will choose the appropriate instance based on either the path prefix or selector parameter (depending upon which features and special parameters you have enabled). If you know exactly which instance is the appropriate one, you may instead call this method on it directly.
The first argument must be the "outer" request object generated by the foundation framework. This allows the Web::DataService code to obtain details about the request and to compose the response using the functionality provided by that framework. This method will create an "inner" object in a subclass of Web::DataService::Request, with attributes derived from the current request and from the data service node that matches it. If no data service node matches the current request, a 404 error response will be returned to the client.
You may provide a second optional argument, which must be a hashref of request attributes (see Web::DataService::Request). These will be used to initialize the request object, overriding any automatically determined attributes.
new_request ( outer, [ attrs ] )
If you wish more control over the request-handling process than is provided by handle_request, you may instead call this method. It returns an object blessed into a subclass of Web::DataService::Request, derived as described above for handle_request.
You can then examine and possibly alter any of the request attributes, before calling the request's execute method. This method may, like handle_request, be called either as a class method or an instance method.
execute_request ( request )
This method may be called to execute a request. The argument must belong to a subclass of Web::DataService::Request, created by a previous call to new_request. This method may, like handle_request, be called either as a class method or an instance method.
node_attr ( path, attribute )
Returns the specified attribute of the node with the specified path, if the specified path and attribute are both defined. Returns undef otherwise. You can use this to test whether a particular node is in fact defined, or to retrieve any node attribute.
You will rarely need to call this method, since for any request the relevant attributes of the matching node will be automatically used to instantiate the request object. In almost all cases, you will instead use the attribute accessor methods of the request object.
config_value ( name )
Returns the value (if any) specified for this name in the application configuration file. If the name is found as a sub-entry under the data service name, that value is used. Otherwise, if the name is found as a top-level entry then it is used.
has_feature ( feature_name )
Returns a true value if the specified feature is enabled for this data service. Returns false otherwise.
special_param ( parameter_name )
If the specified special parameter is enabled for this data service, returns the parameter name which clients use. This may be different from the internal name by which this parameter is known, but will always be a true value. Returns false if this parameter is not enabled.
generate_site_url
This method works the same as the generate_url method of Web::DataService::Request. However, it can only generate URLs of type "rel" or "site". If you want to generate an absolute URL, use the latter method.
get_connection
If a backend plugin is available, this method obtains a connection handle from it. You can use this method when initializing your operation roles, if your initialization process requires communication with the backend. You are not required to use this mechanism, however, and may contact the backend in any way you choose.
accessor methods
Each of the data service attributes is provided with an accessor method. This method returns the attribute value, but cannot be used to set it. All data service attributes must be set when the data service object is instantiated with new, either specified directly in that call or looked up in the application configuration file provided by the foundation framework.
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_vocabs ( 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.
MISCELLANEOUS
valid_name ( name )
Returns true if the given string is valid as a Web::DataService name. This means that it begins with a word character and includes only word characters plus the punctuation characters ':', '-' and '.'.
set_mode ( mode ... )
You can call this either as a class method or as an instance method; it has a global effect either way. This method 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.
You will typically call this at application startup time.
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.