package Catalyst::Controller::REST;
+our $VERSION = '0.72';
+
=head1 NAME
Catalyst::Controller::REST - A RESTful controller
In addition, each serializer has it's quirks in terms of what sorts of data
structures it will properly handle. L<Catalyst::Controller::REST> makes
-no attempt to svae you from yourself in this regard. :)
+no attempt to save you from yourself in this regard. :)
=over 2
This uses L<YAML::Syck> and L<URI::Find> to generate YAML with all URLs turned
to hyperlinks. Only useable for Serialization.
-=item C<text/x-json> => C<JSON::Syck>
+=item C<application/json> => C<JSON>
-Uses L<JSON::Syck> to generate JSON output
+Uses L<JSON> to generate JSON output. It is strongly advised to also have
+L<JSON::XS> installed. The C<text/x-json> content type is supported but is
+deprecated and you will receive warnings in your log.
=item C<text/x-data-dumper> => C<Data::Serializer>
{ data => $yourdata }
+=item L<View>
+
+Uses a regular Catalyst view. For example, if you wanted to have your
+C<text/html> and C<text/xml> views rendered by TT:
+
+ 'text/html' => [ 'View', 'TT' ],
+ 'text/xml' => [ 'View', 'XML' ],
+
+Will do the trick nicely.
+
=back
-By default, L<Catalyst::Controller::REST> will return a C<415 Unsupported Media Type> response if an attempt to use an unsupported content-type is made. You
-can ensure that something is always returned by setting the C<default> config
-option:
+By default, L<Catalyst::Controller::REST> will return a C<415 Unsupported Media Type>
+response if an attempt to use an unsupported content-type is made. You
+can ensure that something is always returned by setting the C<default>
+config option:
- __PACKAGE__->config->{'serialize'}->{'default'} = 'YAML';
+ __PACKAGE__->config->{'default'} = 'text/x-yaml';
-Would make it always fall back to YAML.
+Would make it always fall back to the serializer plugin defined for text/x-yaml.
Implementing new Serialization formats is easy! Contributions
are most welcome! See L<Catalyst::Action::Serialize> and
use strict;
use warnings;
use base 'Catalyst::Controller';
-use Params::Validate qw(:all);
+use Params::Validate qw(SCALAR OBJECT);
__PACKAGE__->mk_accessors(qw(serialize));
__PACKAGE__->config(
- serialize => {
- 'stash_key' => 'rest',
- 'map' => {
- 'text/html' => 'YAML::HTML',
- 'text/xml' => 'XML::Simple',
- 'text/x-yaml' => 'YAML',
- 'text/x-json' => 'JSON',
- 'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
- 'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
- 'text/x-data-taxi' => [ 'Data::Serializer', 'Data::Taxi' ],
- 'application/x-storable' => [ 'Data::Serializer', 'Storable' ],
- 'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw' ],
- 'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ],
- 'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
- },
- }
+ 'stash_key' => 'rest',
+ 'map' => {
+ 'text/html' => 'YAML::HTML',
+ 'text/xml' => 'XML::Simple',
+ 'text/x-yaml' => 'YAML',
+ 'application/json' => 'JSON',
+ 'text/x-json' => 'JSON',
+ 'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
+ 'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
+ 'text/x-data-taxi' => [ 'Data::Serializer', 'Data::Taxi' ],
+ 'application/x-storable' => [ 'Data::Serializer', 'Storable' ],
+ 'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw' ],
+ 'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ],
+ 'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
+ },
);
-sub begin : ActionClass('Deserialize') {
-}
+sub begin : ActionClass('Deserialize') { }
-sub end : ActionClass('Serialize') {
-}
+sub end : ActionClass('Serialize') { }
=item status_ok
sub status_ok {
my $self = shift;
my $c = shift;
- my %p = validate( @_, { entity => 1, }, );
+ my %p = Params::Validate::validate( @_, { entity => 1, }, );
$c->response->status(200);
$self->_set_entity( $c, $p{'entity'} );
sub status_created {
my $self = shift;
my $c = shift;
- my %p = validate(
+ my %p = Params::Validate::validate(
@_,
{
location => { type => SCALAR | OBJECT },
sub status_accepted {
my $self = shift;
my $c = shift;
- my %p = validate( @_, { entity => 1, }, );
+ my %p = Params::Validate::validate( @_, { entity => 1, }, );
$c->response->status(202);
$self->_set_entity( $c, $p{'entity'} );
sub status_bad_request {
my $self = shift;
my $c = shift;
- my %p = validate( @_, { message => { type => SCALAR }, }, );
+ my %p = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
$c->response->status(400);
- $c->log->debug( "Status Bad Request: " . $p{'message'} );
+ $c->log->debug( "Status Bad Request: " . $p{'message'} ) if $c->debug;
$self->_set_entity( $c, { error => $p{'message'} } );
return 1;
}
sub status_not_found {
my $self = shift;
my $c = shift;
- my %p = validate( @_, { message => { type => SCALAR }, }, );
+ my %p = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
$c->response->status(404);
- $c->log->debug( "Status Not Found: " . $p{'message'} );
+ $c->log->debug( "Status Not Found: " . $p{'message'} ) if $c->debug;
$self->_set_entity( $c, { error => $p{'message'} } );
return 1;
}
my $c = shift;
my $entity = shift;
if ( defined($entity) ) {
- $c->stash->{ $self->config->{'serialize'}->{'stash_key'} } = $entity;
+ $c->stash->{ $self->{'stash_key'} } = $entity;
}
return 1;
}
'text/html' => 'YAML::HTML',
'text/xml' => 'XML::Simple',
'text/x-yaml' => 'YAML',
+ 'application/json' => 'JSON',
'text/x-json' => 'JSON',
'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
],
'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ]
,
- 'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serializat
-ion' ],
+ 'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
},
}
);
... do things after Serializing ...
}
+=back
+
=head1 A MILD WARNING
I have code in production using L<Catalyst::Controller::REST>. That said,
Marchex, Inc. paid me while I developed this module. (http://www.marchex.com)
+=head1 MAINTAINER
+
+J. Shirley <jshirley@cpan.org>
+
=head1 LICENSE
You may distribute this code under the same terms as Perl itself.