NAME
Web::DataService - a framework for building data service applications for the Web
VERSION
Version 0.21
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 roles whose methods will handle the "meat" of each 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.
This module then handles the rest of the work necessary for handling each request, including checking the parameter values, determining the output format, 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.
METHODS
CONFIGURATION
The following methods are used to configure a web data service application. For a list of the available attributes for each method, see Web::DataService::Configuration. For detailed instructions on how to set up a data service application, see Web::DataService::Tutorial. These configuration methods will be called at the start of your data service application. The method new is a class method; the others are all instance methods, to be called on the resulting Web::DataService object(s).
new ( { attributes ... } )
This class method defines a new data service instance. Calling it is generally the first step in configuring a web dataservice application. The available attributes are described in Web::DataService::Configuration. The attribute name is required; the others are optional, and may be specified in the application configuration file instead.
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 output 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 the available sets of optional output for various kinds of requests.
define_ruleset ( ruleset_name, { attributes ... }, documentation ... )
Define 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 the request, one of the data service operation methods that you have written may be called as part of this process.
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. The Web::DataService code will create an "inner" object of class Web::DataService::Request, with attributes derived from the current request along with the data service node (if any) 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 of class Web::DataService::Request, derived as described for handle_request.
You can then examine and possibly alter any of the request attributes, before calling execute_request.
execute_request ( request )
This method may be called to execute a request, once the request object has been created and examined. The argument must be an object of class Web::DataService::Request from a previous call to new_request.
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.
get_connection
If a backend plugin is available, obtains a connection handle from it. You can use this method when initializing your data classes, 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.
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.
base_url
Returns the base URL of this data service, in the form "http[s]://hostname[:port]/". Most of the URLs included in the documentation pages will be relative to this base.
root_url
Returns the root URL of this data service, in the form "http[s]://hostname[:port]/[prefix/] where prefix is the path prefix defined for this data service.
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.
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_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.
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.