NAME

Web::DataService::Configuration::Format - how to configure output formats

SYNOPSIS

This page describes the role that output formats play in the Web::DataService framework, and how to configure them. It includes a list of the attributes that you can use to define them.

FORMAT DEFINITIONS

Each data service must define one or more output formats. These are defined using the define_format method of a data service object. This must be be done at data service startup time before any nodes are defined, so that the default_format and allow_format node attributes can be interpreted properly. Each format definition configures one of the available serialization modules.

Predefined formats

The format names listed below are predefined by Web::DataService and can be activated simply by specifying a hashref with the appropriate name attribute. For example, the following call will enable the formats 'json' and 'txt' with all of their default attribute values and documentation strings.

    $ds->define_format(
        { name => 'json' },
        { name => 'txt' });

You can override any of these attribute values and documentation strings by specifying them explicitly. The example code directory contains documentation files for each of these formats, which you can copy into your own application directory and modify as you see fit. However, you must explicitly define the corresponding data service nodes yourself or else the documentation pages will not be available. The corresponding call for this example would be:

    $ds->define_node(
        { path => 'formats',
          title => 'Output formats' },
        { path => 'formats/json',
          title => 'JSON format' },
        { path => 'formats/txt',
          title => 'Plain text format' });

See the next section for descriptions of the various attributes.

json

This format serializes operation results using JSON (JavaScript Object Notation). It sets the content type of the response to "application/json", and its default documentation node is "formats/json". The module used is Web::DataService::Plugins::JSON.

txt

This format serializes operation results as lines of comma-separated values separated by the specified linebreak sequence. Its content type is "text/plain", and its default documentation node is "formats/txt". The module used is Web::DataService::Plugins::Text.

csv

This format is identical to "txt", except that it sets the content type of the response to "text/csv" and sets the content disposition to "attachment".

tsv

This format serializes operation results as lines of tab-separated values separated by the specified linebreak sequence. Its content type is "text/tab-separated-values", and its disposition is "attachment". Its default documentation node is "formats/txt". The module used is Web::DataService::Plugins::Text.

FORMAT ATTRIBUTES

With the exception of name, each of the following attributes is optional for predefined formats. Those which are required for custom (i.e. not predefined) formats are noted below.

name

Each format defined for a given data service must have a unique name. This name can be used as the value of the node attributes allow_format and default_format, and is matched either to the URL path suffix or to the value of the special parameter "format" depending upon which data service features are enabled. This attribute is required for all format definitions.

title

The value of this attribute is used as the format's title in all generated documentation. It defaults to the name.

content_type

The value of this attribute specifies the HTTP content type that will be reported in the response message. It is required for all custom format definitions.

disposition

If this attribute is given the value 'attachment', then any response generated with this format will be returned with a "content-disposition" header indicating that it should be saved to disk. However, if the special parameter "save" is active and a request includes that parameter with the value "no", then this attribute will be overridden for that request.

The value of this attribute defaults to 'inline' if not specified.

module

The value of this attribute must be the name of a Perl module implementing this format. This module will be automatically loaded via require. You must specify this attribute when defining a custom format, and then include a module with the corresponding name in the appropriate library directory.

doc_node

The value of this attribute specifies the path of a data service node which will provide documentation about this format. You must define the node with a separate call to define_node.

doc_string

You can set this attribute either directly or by including one or more documentation strings after each format definition hash in the call to define_format. This value will be used in any auto-generated format lists in the documentation pages.

default_vocab

The value of this attribute must be the name of an already-defined vocabulary. This vocabulary will be used when rendering responses in this format, unless overridden by the special parameter vocab. It defaults to 'null', which simply uses the underlying field names from the backend data store.

uses_header

The special parameter header will only be enabled if at least one enabled output format uses it. If you are defining a custom format that includes an optional header, you should give this attribute a true value. All of the Text builtin formats set this by default.

is_text

If this attribute is given a true value, then the output of this format is assumed to be structured text. Responses in this format are then able to be displayed in browser pages, if the request includes the parameter save=no, even if they would otherwise be saved to disk. This attribute is set to true for all of the predefined formats.

disabled

If this attribute is given a true value, then any request that selects this format will get an HTTP 415 error response ("Invalid media type") just as if an undefined format was requested. This format can still be used as a value of the node attribute allow_format. You can use this to create a placeholder for a format that is not fully implemented yet, or to temporarily disable a format. Disabled formats will not appear in any auto-generated documentation lists.

undocumented

If this attribute is given a true value, the format will be available to be selected in the usual way, but it will never appear in any auto-generated documentation list.

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.

cpanm Web::DataService

perl -MCPAN -e shell
install Web::DataService