package Catalyst::Controller::REST;
-use strict;
-use warnings;
+use Moose;
+use namespace::autoclean;
-our $VERSION = '0.78';
+our $VERSION = '0.82';
$VERSION = eval $VERSION;
=head1 NAME
=head1 SYNOPSIS
package Foo::Controller::Bar;
-
- use base 'Catalyst::Controller::REST';
+ use Moose;
+ use namespace::autoclean;
+
+ BEGIN { extends 'Catalyst::Controller::REST' }
sub thing : Local : ActionClass('REST') { }
# Answer PUT requests to "thing"
sub thing_PUT {
- ... some action ...
- }
+ $radiohead = $req->data->{radiohead};
+
+ $self->status_created(
+ $c,
+ location => $c->req->uri->as_string,
+ entity => {
+ radiohead => $radiohead,
+ }
+ );
+ }
=head1 DESCRIPTION
of the incoming request. It is probably easier to use the L<STATUS HELPERS>,
which are described below.
-The HTTP POST, PUT, and OPTIONS methods will all automatically deserialize the
-contents of $c->request->body based on the requests content-type header.
-A list of understood serialization formats is below.
+"The HTTP POST, PUT, and OPTIONS methods will all automatically
+L<deserialize|Catalyst::Action::Deserialize> the contents of
+C<< $c->request->body >> into the C<< $c->request->data >> hashref", based on
+the request's C<Content-type> header. A list of understood serialization
+formats is L<below|/AVAILABLE SERIALIZERS>.
If we do not have (or cannot run) a serializer for a given content-type, a 415
"Unsupported Media Type" error is generated.
To make your Controller RESTful, simply have it
- BEGIN {extends 'Catalyst::Controller::REST'; }
-
-Or if you use pre-Moose Catalyst versions,
+ BEGIN { extends 'Catalyst::Controller::REST' }
- use parent 'Catalyst::Controller::REST';
+=head1 CONFIGURATION
+See L<Catalyst::Action::Serialize/CONFIGURATION>. Note that the C<serialize>
+key has been deprecated.
=head1 SERIALIZATION
which serializer to use by mapping a content-type to a Serialization module.
We select the content-type based on:
-=over 2
+=over
=item B<The Content-Type Header>
=back
-
=head1 AVAILABLE SERIALIZERS
A given serialization mechanism is only available if you have the underlying
=item * C<text/html> => C<YAML::HTML>
This uses L<YAML::Syck> and L<URI::Find> to generate YAML with all URLs turned
-to hyperlinks. Only useable for Serialization.
+to hyperlinks. Only usable for Serialization.
=item * C<application/json> => C<JSON>
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/javascript> => C<JSONP>
+
+If a callback=? parameter is passed, this returns javascript in the form of: $callback($serializedJSON);
+
=item * C<text/x-data-dumper> => C<Data::Serializer>
Uses the L<Data::Serializer> module to generate L<Data::Dumper> output.
'text/html' => [ 'View', 'TT' ],
'text/xml' => [ 'View', 'XML' ],
}
- );
+ );
Your views should have a C<process> method like this:
sub process {
my ( $self, $c, $stash_key ) = @_;
-
+
my $output;
eval {
$output = $self->serialize( $c->stash->{$stash_key} );
};
return $@ if $@;
-
+
$c->response->body( $output );
return 1; # important
}
sub serialize {
my ( $self, $data ) = @_;
-
+
my $serialized = ... process $data here ...
-
+
return $serialized;
}
-
=back
content-type is made. You can ensure that something is always returned by
setting the C<default> config option:
- __PACKAGE__->config->{'default'} = 'text/x-yaml';
+ __PACKAGE__->config(default => 'text/x-yaml');
would make it always fall back to the serializer plugin defined for
C<text/x-yaml>.
These routines are all implemented as regular subroutines, and as
such require you pass the current context ($c) as the first argument.
-=over 4
+=over
=cut
-use base 'Catalyst::Controller';
+BEGIN { extends 'Catalyst::Controller' }
use Params::Validate qw(SCALAR OBJECT);
__PACKAGE__->mk_accessors(qw(serialize));
'text/x-yaml' => 'YAML',
'application/json' => 'JSON',
'text/x-json' => 'JSON',
+ 'application/x-javascript' => 'JSONP',
+ 'application/javascript' => 'JSONP',
+ 'text/javascript' => 'JSONP',
'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
'text/x-data-taxi' => [ 'Data::Serializer', 'Data::Taxi' ],
'text/x-yaml' => 'YAML',
'application/json' => 'JSON',
'text/x-json' => 'JSON',
+ 'application/x-javascript' => 'JSONP',
+ 'application/javascript' => 'JSONP',
+ 'text/javascript' => 'JSONP',
'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
'text/x-data-taxi' => [ 'Data::Serializer', 'Data::Taxi' ],
either behavior, simply implement your own C<begin> and C<end> actions
and use MRO::Compat:
- my Foo::Controller::Monkey;
- use base qw(Catalyst::Controller::REST);
+ package Foo::Controller::Monkey;
+ use Moose;
+ use namespace::autoclean;
+
+ BEGIN { extends 'Catalyst::Controller::REST' }
sub begin :Private {
my ($self, $c) = @_;
I have code in production using L<Catalyst::Controller::REST>. That said,
it is still under development, and it's possible that things may change
-between releases. I promise to not break things unneccesarily. :)
+between releases. I promise to not break things unnecessarily. :)
=head1 SEE ALSO
The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
-=head1 AUTHOR
-
-Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and jrockway
-
-Marchex, Inc. paid me while I developed this module. (http://www.marchex.com)
-
-=head1 MAINTAINER
+=head1 AUTHORS
-J. Shirley <jshirley@cpan.org>
+See L<Catalyst::Action::REST> for authors.
=head1 LICENSE
projects / catagits/Catalyst-Action-REST.git / blobdiff