X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FController%2FREST.pm;h=d185a0bb31c15af0c1d0b7150dd3d651e42f3e34;hb=bbf0feae0566317258d7bdd47d70a0b68a2a583f;hp=9608495c1e74311186ec07d7e6af7fec73005419;hpb=6023cdb2549051852342f4b0e2ec67b9d888da78;p=catagits%2FCatalyst-Action-REST.git diff --git a/lib/Catalyst/Controller/REST.pm b/lib/Catalyst/Controller/REST.pm index 9608495..d185a0b 100644 --- a/lib/Catalyst/Controller/REST.pm +++ b/lib/Catalyst/Controller/REST.pm @@ -1,10 +1,13 @@ package Catalyst::Controller::REST; +use strict; +use warnings; -our $VERSION = 0.64; +our $VERSION = '0.75'; +$VERSION = eval $VERSION; =head1 NAME -Catalyst::Controller::REST - A RESTful controller +Catalyst::Controller::REST - A RESTful controller =head1 SYNOPSIS @@ -17,11 +20,11 @@ Catalyst::Controller::REST - A RESTful controller # 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', @@ -30,7 +33,7 @@ Catalyst::Controller::REST - A RESTful controller } # Answer PUT requests to "thing" - sub thing_PUT { + sub thing_PUT { .. some action .. } @@ -38,23 +41,23 @@ Catalyst::Controller::REST - A RESTful controller 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 method. +C 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. @@ -69,18 +72,18 @@ contents of $c->request->body based on the requests content-type header. 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 @@ -95,7 +98,7 @@ If this is a GET request, you can supply a content-type query parameter. =item B 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 @@ -103,11 +106,11 @@ it and use the best-ranked choice. 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 makes -no attempt to svae you from yourself in this regard. :) +no attempt to save you from yourself in this regard. :) =over 2 @@ -120,9 +123,11 @@ Returns YAML generated by L. This uses L and L to generate YAML with all URLs turned to hyperlinks. Only useable for Serialization. -=item C => C +=item C => C -Uses L to generate JSON output +Uses L to generate JSON output. It is strongly advised to also have +L installed. The C content type is supported but is +deprecated and you will receive warnings in your log. =item C => C @@ -162,13 +167,13 @@ you serialize be a HASHREF, we transform outgoing data to be in the form of: =item L -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 and C 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 @@ -177,7 +182,7 @@ response if an attempt to use an unsupported content-type is made. You can ensure that something is always returned by setting the C 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. @@ -199,7 +204,7 @@ Using them will ensure that you are responding with the proper codes, headers, and entities. These helpers try and conform to the HTTP 1.1 Specification. You can -refer to it at: L. +refer to it at: L. These routines are all implemented as regular subroutines, and as such require you pass the current context ($c) as the first argument. @@ -207,36 +212,32 @@ 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); __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' ], - }, + '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 @@ -245,7 +246,7 @@ Returns a "200 OK" response. Takes an "entity" to serialize. Example: $self->status_ok( - $c, + $c, entity => { radiohead => "Is a good band!", } @@ -271,7 +272,7 @@ and a "location" where the created object can be found. Example: $self->status_created( - $c, + $c, location => $c->req->uri->as_string, entity => { radiohead => "Is a good band!", @@ -313,7 +314,7 @@ Returns a "202 ACCEPTED" response. Takes an "entity" to serialize. Example: $self->status_accepted( - $c, + $c, entity => { status => "queued", } @@ -331,6 +332,20 @@ sub status_accepted { 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 @@ -340,7 +355,7 @@ response. Example: $self->status_bad_request( - $c, + $c, message => "Cannot do what you have asked!", ); @@ -366,7 +381,7 @@ response. Example: $self->status_not_found( - $c, + $c, message => "Cannot find what you were looking for!", ); @@ -383,6 +398,31 @@ sub status_not_found { 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; @@ -423,9 +463,9 @@ This class provides a default configuration for Serialization. It is currently: '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' ] , @@ -442,7 +482,7 @@ L. The C method uses L. The C method uses L. If you want to override either behavior, simply implement your own C and C actions -and use NEXT: +and use MRO::Compat: my Foo::Controller::Monkey; use base qw(Catalyst::Controller::REST); @@ -450,17 +490,19 @@ and use NEXT: 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 ... } +=back + =head1 A MILD WARNING I have code in production using L. That said, @@ -486,6 +528,10 @@ Adam Jacob , with lots of help from mst and jrockway Marchex, Inc. paid me while I developed this module. (http://www.marchex.com) +=head1 MAINTAINER + +J. Shirley + =head1 LICENSE You may distribute this code under the same terms as Perl itself.