package Catalyst::Controller::REST;
+use strict;
+use warnings;
-our $VERSION = '0.72';
+our $VERSION = '0.78';
+$VERSION = eval $VERSION;
=head1 NAME
-Catalyst::Controller::REST - A RESTful controller
+Catalyst::Controller::REST - A RESTful controller
=head1 SYNOPSIS
# 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 {
+ sub thing_PUT {
.. some action ..
}
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.
A list of understood serialization formats is below.
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';
+ use base 'Catalyst::Controller::REST';
=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
=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
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<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 L<View>
-Uses a regular Catalyst view. For example, if you wanted to have your
+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.
+ 'text/html' => [ 'View', 'TT' ],
+ 'text/xml' => [ 'View', 'XML' ],
+
+Will do the trick nicely.
=back
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 text/x-yaml.
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.
=cut
-use strict;
-use warnings;
use base 'Catalyst::Controller';
use Params::Validate qw(SCALAR OBJECT);
Example:
$self->status_ok(
- $c,
+ $c,
entity => {
radiohead => "Is a good band!",
}
Example:
$self->status_created(
- $c,
+ $c,
location => $c->req->uri->as_string,
entity => {
radiohead => "Is a good band!",
Example:
$self->status_accepted(
- $c,
+ $c,
entity => {
status => "queued",
}
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_bad_request
Returns a "400 BAD REQUEST" response. Takes a "message" argument
Example:
$self->status_bad_request(
- $c,
+ $c,
message => "Cannot do what you have asked!",
);
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;
+}
+
sub _set_entity {
my $self = shift;
my $c = shift;
'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-storable' => [ 'Data::Serializer', 'Storable'
],
- 'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw'
+ 'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw'
],
'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ]
,
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 NEXT:
+and use MRO::Compat:
my Foo::Controller::Monkey;
use base qw(Catalyst::Controller::REST);
sub begin :Private {
my ($self, $c) = @_;
... do things before Deserializing ...
- $self->NEXT::begin($c);
+ $self->maybe::next::method($c);
... do things after Deserializing ...
- }
+ }
sub end :Private {
my ($self, $c) = @_;
... do things before Serializing ...
- $self->NEXT::end($c);
+ $self->maybe::next::method($c);
... do things after Serializing ...
}
projects / catagits/Catalyst-Action-REST.git / blobdiff