package Catalyst::Controller::REST;
+use Moose;
+use namespace::autoclean;
-our $VERSION = '0.73';
+# VERSION
=head1 NAME
-Catalyst::Controller::REST - A RESTful controller
+Catalyst::Controller::REST - A RESTful controller
=head1 SYNOPSIS
package Foo::Controller::Bar;
+ use Moose;
+ use namespace::autoclean;
- use base 'Catalyst::Controller::REST';
+ BEGIN { extends 'Catalyst::Controller::REST' }
sub thing : Local : ActionClass('REST') { }
# Answer GET requests to "thing"
sub thing_GET {
my ( $self, $c ) = @_;
-
+
# Return a 200 OK, with the data in entity
- # serialized in the body
+ # serialized in the body
$self->status_ok(
- $c,
+ $c,
entity => {
some => 'data',
foo => 'is real bar-y',
}
# Answer PUT requests to "thing"
- sub thing_PUT {
- .. some action ..
+ sub thing_PUT {
+ my ( $self, $c ) = @_;
+
+ $radiohead = $c->req->data->{radiohead};
+
+ $self->status_created(
+ $c,
+ location => $c->req->uri,
+ entity => {
+ radiohead => $radiohead,
+ }
+ );
}
=head1 DESCRIPTION
Catalyst::Controller::REST implements a mechanism for building
RESTful services in Catalyst. It does this by extending the
-normal Catalyst dispatch mechanism to allow for different
-subroutines to be called based on the HTTP Method requested,
+normal Catalyst dispatch mechanism to allow for different
+subroutines to be called based on the HTTP Method requested,
while also transparently handling all the serialization/deserialization for
you.
This is probably best served by an example. In the above
controller, we have declared a Local Catalyst action on
-"sub thing", and have used the ActionClass('REST').
+"sub thing", and have used the ActionClass('REST').
Below, we have declared "thing_GET" and "thing_PUT". Any
-GET requests to thing will be dispatched to "thing_GET",
-while any PUT requests will be dispatched to "thing_PUT".
+GET requests to thing will be dispatched to "thing_GET",
+while any PUT requests will be dispatched to "thing_PUT".
Any unimplemented HTTP methods will be met with a "405 Method Not Allowed"
response, automatically containing the proper list of available methods. You
can override this behavior through implementing a custom
-C<thing_not_implemented> method.
+C<thing_not_implemented> method.
If you do not provide an OPTIONS handler, we will respond to any OPTIONS
requests with a "200 OK", populating the Allowed header automatically.
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.
+"Unsupported Media Type" error is generated.
To make your Controller RESTful, simply have it
- use base 'Catalyst::Controller::REST';
+ BEGIN { extends 'Catalyst::Controller::REST' }
+
+=head1 CONFIGURATION
+
+See L<Catalyst::Action::Serialize/CONFIGURATION>. Note that the C<serialize>
+key has been deprecated.
=head1 SERIALIZATION
Catalyst::Controller::REST will automatically serialize your
responses, and deserialize any POST, PUT or OPTIONS requests. It evaluates
which serializer to use by mapping a content-type to a Serialization module.
-We select the content-type based on:
+We select the content-type based on:
-=over 2
+=over
=item B<The Content-Type Header>
=item B<Evaluating the Accept Header>
Finally, if the client provided an Accept header, we will evaluate
-it and use the best-ranked choice.
+it and use the best-ranked choice.
=back
A given serialization mechanism is only available if you have the underlying
modules installed. For example, you can't use XML::Simple if it's not already
-installed.
+installed.
-In addition, each serializer has it's quirks in terms of what sorts of data
+In addition, each serializer has its quirks in terms of what sorts of data
structures it will properly handle. L<Catalyst::Controller::REST> makes
-no attempt to save you from yourself in this regard. :)
+no attempt to save you from yourself in this regard. :)
=over 2
-=item C<text/x-yaml> => C<YAML::Syck>
+=item * C<text/x-yaml> => C<YAML::Syck>
Returns YAML generated by L<YAML::Syck>.
-=item C<text/html> => C<YAML::HTML>
+=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>
+=item * C<application/json> => C<JSON>
-Uses L<JSON> to generate JSON output. It is strongly advised to also have
+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>
+You can also add a hash in your controller config to pass options to the json object.
+For instance, to relax permissions when deserializing input, add:
+ __PACKAGE__->config(
+ json_options => { relaxed => 1 }
+ )
-Uses the L<Data::Serializer> module to generate L<Data::Dumper> output.
+=item * C<text/javascript> => C<JSONP>
-=item C<text/x-data-denter> => C<Data::Serializer>
+If a callback=? parameter is passed, this returns javascript in the form of: $callback($serializedJSON);
-Uses the L<Data::Serializer> module to generate L<Data::Denter> output.
+Note - this is disabled by default as it can be a security risk if you are unaware.
-=item C<text/x-data-taxi> => C<Data::Serializer>
+The usual MIME types for this serialization format are: 'text/javascript', 'application/x-javascript',
+'application/javascript'.
-Uses the L<Data::Serializer> module to generate L<Data::Taxi> output.
+=item * C<text/x-data-dumper> => C<Data::Serializer>
-=item C<application/x-storable> => C<Data::Serializer>
+Uses the L<Data::Serializer> module to generate L<Data::Dumper> output.
-Uses the L<Data::Serializer> module to generate L<Storable> output.
+=item * C<text/x-data-denter> => C<Data::Serializer>
-=item C<application/x-freezethaw> => C<Data::Serializer>
+Uses the L<Data::Serializer> module to generate L<Data::Denter> output.
-Uses the L<Data::Serializer> module to generate L<FreezeThaw> output.
+=item * C<text/x-data-taxi> => C<Data::Serializer>
-=item C<text/x-config-general> => C<Data::Serializer>
+Uses the L<Data::Serializer> module to generate L<Data::Taxi> output.
+
+=item * C<text/x-config-general> => C<Data::Serializer>
Uses the L<Data::Serializer> module to generate L<Config::General> output.
-=item C<text/x-php-serialization> => C<Data::Serializer>
+=item * C<text/x-php-serialization> => C<Data::Serializer>
Uses the L<Data::Serializer> module to generate L<PHP::Serialization> output.
-=item C<text/xml> => C<XML::Simple>
+=item * C<text/xml> => C<XML::Simple>
Uses L<XML::Simple> to generate XML output. This is probably not suitable
for any real heavy XML work. Due to L<XML::Simple>s requirement that the data
{ data => $yourdata }
-=item L<View>
+=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:
+Uses a regular Catalyst view. For example, if you wanted to have your
+C<text/html> and C<text/xml> views rendered by TT, set:
- 'text/html' => [ 'View', 'TT' ],
- 'text/xml' => [ 'View', 'XML' ],
-
-Will do the trick nicely.
+ __PACKAGE__->config(
+ map => {
+ 'text/html' => [ 'View', 'TT' ],
+ 'text/xml' => [ 'View', 'XML' ],
+ }
+ );
-=back
+Your views should have a C<process> method like this:
-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:
+ sub process {
+ my ( $self, $c, $stash_key ) = @_;
- __PACKAGE__->config->{'default'} = 'text/x-yaml';
+ my $output;
+ eval {
+ $output = $self->serialize( $c->stash->{$stash_key} );
+ };
+ return $@ if $@;
-Would make it always fall back to the serializer plugin defined for text/x-yaml.
+ $c->response->body( $output );
+ return 1; # important
+ }
-Implementing new Serialization formats is easy! Contributions
-are most welcome! See L<Catalyst::Action::Serialize> and
-L<Catalyst::Action::Deserialize> for more information.
+ sub serialize {
+ my ( $self, $data ) = @_;
+
+ my $serialized = ... process $data here ...
+
+ return $serialized;
+ }
+
+=item * Callback
+
+For infinite flexibility, you can provide a callback for the
+deserialization/serialization steps.
+
+ __PACKAGE__->config(
+ map => {
+ 'text/xml' => [ 'Callback', { deserialize => \&parse_xml, serialize => \&render_xml } ],
+ }
+ );
+
+The C<deserialize> callback is passed a string that is the body of the
+request and is expected to return a scalar value that results from
+the deserialization. The C<serialize> callback is passed the data
+structure that needs to be serialized and must return a string suitable
+for returning in the HTTP response. In addition to receiving the scalar
+to act on, both callbacks are passed the controller object and the context
+(i.e. C<$c>) as the second and third arguments.
+
+=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:
+
+ __PACKAGE__->config(default => 'text/x-yaml');
+
+would make it always fall back to the serializer plugin defined for
+C<text/x-yaml>.
=head1 CUSTOM SERIALIZERS
-If you would like to implement a custom serializer, you should create two new
-modules in the L<Catalyst::Action::Serialize> and
-L<Catalyst::Action::Deserialize> namespace. Then assign your new class
-to the content-type's you want, and you're done.
+Implementing new Serialization formats is easy! Contributions
+are most welcome! If you would like to implement a custom serializer,
+you should create two new modules in the L<Catalyst::Action::Serialize>
+and L<Catalyst::Action::Deserialize> namespace. Then assign your new
+class to the content-type's you want, and you're done.
+
+See L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>
+for more information.
=head1 STATUS HELPERS
headers, and entities.
These helpers try and conform to the HTTP 1.1 Specification. You can
-refer to it at: L<http://www.w3.org/Protocols/rfc2616/rfc2616.txt>.
+refer to it at: L<http://www.w3.org/Protocols/rfc2616/rfc2616.txt>.
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 strict;
-use warnings;
-use base 'Catalyst::Controller';
+BEGIN { extends 'Catalyst::Controller' }
use Params::Validate qw(SCALAR OBJECT);
__PACKAGE__->mk_accessors(qw(serialize));
__PACKAGE__->config(
'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' ],
},
);
Example:
$self->status_ok(
- $c,
+ $c,
entity => {
radiohead => "Is a good band!",
}
Example:
$self->status_created(
- $c,
- location => $c->req->uri->as_string,
+ $c,
+ location => $c->req->uri,
entity => {
radiohead => "Is a good band!",
}
},
);
- my $location;
- if ( ref( $p{'location'} ) ) {
- $location = $p{'location'}->as_string;
- } else {
- $location = $p{'location'};
- }
$c->response->status(201);
- $c->response->header( 'Location' => $location );
+ $c->response->header( 'Location' => $p{location} );
$self->_set_entity( $c, $p{'entity'} );
return 1;
}
=item status_accepted
Returns a "202 ACCEPTED" response. Takes an "entity" to serialize.
+Also takes optional "location" for queue type scenarios.
Example:
$self->status_accepted(
- $c,
+ $c,
+ location => $c->req->uri,
entity => {
status => "queued",
}
sub status_accepted {
my $self = shift;
my $c = shift;
- my %p = Params::Validate::validate( @_, { entity => 1, }, );
+ my %p = Params::Validate::validate(
+ @_,
+ {
+ location => { type => SCALAR | OBJECT, optional => 1 },
+ entity => 1,
+ },
+ );
$c->response->status(202);
+ $c->response->header( 'Location' => $p{location} ) if exists $p{location};
+ $self->_set_entity( $c, $p{'entity'} );
+ return 1;
+}
+
+=item status_no_content
+
+Returns a "204 NO CONTENT" response.
+
+=cut
+
+sub status_no_content {
+ my $self = shift;
+ my $c = shift;
+ $c->response->status(204);
+ $self->_set_entity( $c, undef );
+ return 1;
+}
+
+=item status_multiple_choices
+
+Returns a "300 MULTIPLE CHOICES" response. Takes an "entity" to serialize, which should
+provide list of possible locations. Also takes optional "location" for preferred choice.
+
+=cut
+
+sub status_multiple_choices {
+ my $self = shift;
+ my $c = shift;
+ my %p = Params::Validate::validate(
+ @_,
+ {
+ entity => 1,
+ location => { type => SCALAR | OBJECT, optional => 1 },
+ },
+ );
+
+ $c->response->status(300);
+ $c->response->header( 'Location' => $p{location} ) if exists $p{'location'};
+ $self->_set_entity( $c, $p{'entity'} );
+ return 1;
+}
+
+=item status_found
+
+Returns a "302 FOUND" response. Takes an "entity" to serialize.
+Also takes optional "location".
+
+=cut
+
+sub status_found {
+ my $self = shift;
+ my $c = shift;
+ my %p = Params::Validate::validate(
+ @_,
+ {
+ entity => 1,
+ location => { type => SCALAR | OBJECT, optional => 1 },
+ },
+ );
+
+ $c->response->status(302);
+ $c->response->header( 'Location' => $p{location} ) if exists $p{'location'};
$self->_set_entity( $c, $p{'entity'} );
return 1;
}
Example:
$self->status_bad_request(
- $c,
+ $c,
message => "Cannot do what you have asked!",
);
return 1;
}
+=item status_forbidden
+
+Returns a "403 FORBIDDEN" response. Takes a "message" argument
+as a scalar, which will become the value of "error" in the serialized
+response.
+
+Example:
+
+ $self->status_forbidden(
+ $c,
+ message => "access denied",
+ );
+
+=cut
+
+sub status_forbidden {
+ my $self = shift;
+ my $c = shift;
+ my %p = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
+
+ $c->response->status(403);
+ $c->log->debug( "Status Forbidden: " . $p{'message'} ) if $c->debug;
+ $self->_set_entity( $c, { error => $p{'message'} } );
+ return 1;
+}
+
=item status_not_found
Returns a "404 NOT FOUND" response. Takes a "message" argument
Example:
$self->status_not_found(
- $c,
+ $c,
message => "Cannot find what you were looking for!",
);
return 1;
}
+=item gone
+
+Returns a "41O GONE" response. Takes a "message" argument as a scalar,
+which will become the value of "error" in the serialized response.
+
+Example:
+
+ $self->status_gone(
+ $c,
+ message => "The document have been deleted by foo",
+ );
+
+=cut
+
+sub status_gone {
+ my $self = shift;
+ my $c = shift;
+ my %p = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
+
+ $c->response->status(410);
+ $c->log->debug( "Status Gone " . $p{'message'} ) if $c->debug;
+ $self->_set_entity( $c, { error => $p{'message'} } );
+ return 1;
+}
+
+=item status_see_other
+
+Returns a "303 See Other" response. Takes an optional "entity" to serialize,
+and a "location" where the client should redirect to.
+
+Example:
+
+ $self->status_see_other(
+ $c,
+ location => $some_other_url,
+ entity => {
+ radiohead => "Is a good band!",
+ }
+ );
+
+=cut
+
+sub status_see_other {
+ my $self = shift;
+ my $c = shift;
+ my %p = Params::Validate::validate(
+ @_,
+ {
+ location => { type => SCALAR | OBJECT },
+ entity => { optional => 1 },
+ },
+ );
+
+ $c->response->status(303);
+ $c->response->header( 'Location' => $p{location} );
+ $self->_set_entity( $c, $p{'entity'} );
+ return 1;
+}
+
+=item status_moved
+
+Returns a "301 MOVED" response. Takes an "entity" to serialize, and a
+"location" where the created object can be found.
+
+Example:
+
+ $self->status_moved(
+ $c,
+ location => '/somewhere/else',
+ entity => {
+ radiohead => "Is a good band!",
+ },
+ );
+
+=cut
+
+sub status_moved {
+ my $self = shift;
+ my $c = shift;
+ my %p = Params::Validate::validate(
+ @_,
+ {
+ location => { type => SCALAR | OBJECT },
+ entity => { optional => 1 },
+ },
+ );
+
+ my $location = ref $p{location}
+ ? $p{location}->as_string
+ : $p{location}
+ ;
+
+ $c->response->status(301);
+ $c->response->header( Location => $location );
+ $self->_set_entity($c, $p{entity});
+ return 1;
+}
+
sub _set_entity {
my $self = shift;
my $c = shift;
This class provides a default configuration for Serialization. It is currently:
__PACKAGE__->config(
- serialize => {
- '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' ],
- },
- }
+ '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' ],
+ },
);
You can read the full set of options for this configuration block in
The C<begin> method uses L<Catalyst::Action::Deserialize>. The C<end>
method uses L<Catalyst::Action::Serialize>. If you want to override
either behavior, simply implement your own C<begin> and C<end> actions
-and use MRO::Compat:
+and forward to another action with the Serialize and/or Deserialize
+action classes:
+
+ package Foo::Controller::Monkey;
+ use Moose;
+ use namespace::autoclean;
- my Foo::Controller::Monkey;
- use base qw(Catalyst::Controller::REST);
+ BEGIN { extends 'Catalyst::Controller::REST' }
- sub begin :Private {
+ sub begin : Private {
my ($self, $c) = @_;
- ... do things before Deserializing ...
- $self->maybe::next::method($c);
+ ... do things before Deserializing ...
+ $c->forward('deserialize');
... do things after Deserializing ...
- }
+ }
+
+ sub deserialize : ActionClass('Deserialize') {}
sub end :Private {
my ($self, $c) = @_;
- ... do things before Serializing ...
- $self->maybe::next::method($c);
+ ... do things before Serializing ...
+ $c->forward('serialize');
... do things after Serializing ...
}
+ sub serialize : ActionClass('Serialize') {}
+
+If you need to deserialize multipart requests (i.e. REST data in
+one part and file uploads in others) you can do so by using the
+L<Catalyst::Action::DeserializeMultiPart> action class.
+
=back
=head1 A MILD WARNING
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 AUTHORS
-=head1 MAINTAINER
-
-J. Shirley <jshirley@cpan.org>
+See L<Catalyst::Action::REST> for authors.
=head1 LICENSE
=cut
+__PACKAGE__->meta->make_immutable;
+
1;