package Catalyst::Controller::REST;
+
use Moose;
use namespace::autoclean;
-our $VERSION = '0.93';
-$VERSION = eval $VERSION;
-
=head1 NAME
Catalyst::Controller::REST - A RESTful controller
package Foo::Controller::Bar;
use Moose;
use namespace::autoclean;
-
+
BEGIN { extends 'Catalyst::Controller::REST' }
sub thing : Local : ActionClass('REST') { }
my ( $self, $c ) = @_;
$radiohead = $c->req->data->{radiohead};
-
+
$self->status_created(
$c,
- location => $c->req->uri->as_string,
+ location => $c->req->uri,
entity => {
radiohead => $radiohead,
}
);
- }
+ }
=head1 DESCRIPTION
"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
+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>.
Uses the L<Data::Serializer> module to generate L<Data::Taxi> output.
-=item * C<application/x-storable> => C<Data::Serializer>
-
-Uses the L<Data::Serializer> module to generate L<Storable> output.
-
-=item * C<application/x-freezethaw> => C<Data::Serializer>
-
-Uses the L<Data::Serializer> module to generate L<FreezeThaw> output.
-
=item * C<text/x-config-general> => C<Data::Serializer>
Uses the L<Data::Serializer> module to generate L<Config::General> output.
$c->response->body( $output );
return 1; # important
}
-
+
sub serialize {
my ( $self, $data ) = @_;
=back
-By default, L<Catalyst::Controller::REST> will return a
+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:
=head1 CUSTOM SERIALIZERS
Implementing new Serialization formats is easy! Contributions
-are most welcome! If you would like to implement a custom serializer,
+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>
+See L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>
for more information.
=head1 STATUS HELPERS
__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' ],
},
+ 'compliance_mode' => 0,
);
sub begin : ActionClass('Deserialize') { }
$self->status_created(
$c,
- location => $c->req->uri->as_string,
+ 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,
+ 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;
}
},
);
- my $location;
- if ( ref( $p{'location'} ) ) {
- $location = $p{'location'}->as_string;
- } else {
- $location = $p{'location'};
- }
$c->response->status(300);
- $c->response->header( 'Location' => $location ) if exists $p{'location'};
+ $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" for preferred choice.
+Also takes optional "location".
=cut
},
);
- my $location;
- if ( ref( $p{'location'} ) ) {
- $location = $p{'location'}->as_string;
- } else {
- $location = $p{'location'};
- }
$c->response->status(302);
- $c->response->header( 'Location' => $location ) if exists $p{'location'};
+ $c->response->header( 'Location' => $p{location} ) if exists $p{'location'};
$self->_set_entity( $c, $p{'entity'} );
return 1;
}
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;
projects / catagits/Catalyst-Action-REST.git / blobdiff