X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README;h=00e1bbbc4143ac78f8f0b582fdb526e44a1410bc;hb=09fbacb73fa99be904e786c14b2f41420e5f4bf4;hp=f7175e251ba3a492dadce69cc47fa7ae6ecbf043;hpb=01f9819aaf3c33459ffb2c9005a32ad59eee8663;p=catagits%2FCatalyst-Action-Serialize-Data-Serializer.git diff --git a/README b/README index f7175e2..00e1bbb 100644 --- a/README +++ b/README @@ -1,176 +1,69 @@ NAME - Catalyst::Controller::REST - A RESTful controller + Catalyst::Action::Serialize::Data::Serializer - Serialize with + Data::Serializer SYNOPSIS - package Foo::Controller::Bar; - - use base '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 - $self->status_ok( - $c, - entity => { - some => 'data', - foo => 'is real bar-y', - }, - ); - } - - # Answer PUT requests to "thing" - sub thing_PUT { - .. some action .. - } + package MyApp::Controller::Foo; -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, 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'). - - 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". - - Any unimplemented HTTP METHODS will be met with a "405 Method Not - Allowed" response, automatically containing the proper list of available - methods. - - 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. - - Also included in this class are several helper methods, which will - automatically handle setting up proper response objects for you. - - To make your Controller RESTful, simply have it - - use base 'Catalyst::Controller::REST'; - -SERIALIZATION - Catalyst::Controller::REST will automatically serialize your responses. - The currently implemented serialization formats are: - - text/x-yaml -> YAML::Syck - text/x-data-dumper -> Data::Serializer - - By default, Catalyst::Controller::REST will use YAML as the - serialization format. - - Implementing new Serialization formats is easy! Contributions are most - welcome! See Catalyst::Action::Serialize and - Catalyst::Action::Deserialize for more information. - -STATUS HELPERS - These helpers try and conform to the HTTP 1.1 Specification. You can - refer to it at: 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. - - status_ok - Returns a "200 OK" response. Takes an "entity" to serialize. - - Example: + use Moose; + use namespace::autoclean; - $self->status_ok( - $c, - entity => { - radiohead => "Is a good band!", - } - ); + BEGIN { extends 'Catalyst::Controller' } - status_created - Returns a "201 CREATED" response. Takes an "entity" to serialize, - and a "location" where the created object can be found. + __PACKAGE__->config( + 'default' => 'text/x-yaml', + 'stash_key' => 'rest', + 'map' => { + 'text/x-yaml' => 'YAML', + 'application/json' => 'JSON', + 'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ], + }, + ); - Example: - - $self->status_created( - $c, - location => $c->req->uri->as_string, - entity => { - radiohead => "Is a good band!", - } - ); - - In the above example, we use the requested URI as our location. This - is probably what you want for most PUT requests. +DESCRIPTION + This module implements a serializer for use with "Data::Dumper" and + others. It was factored out of Catalyst::Action::REST because it is + unlikely to be widely used and tends to break tests, be insecure, and is + generally weird. Use at your own risk. - status_accepted - Returns a "202 ACCEPTED" response. Takes an "entity" to serialize. +AUTHOR + Adam Jacob , with lots of help from mst and + jrockway - Example: + Marchex, Inc. paid me while I developed this module. + () - $self->status_accepted( - $c, - entity => { - status => "queued", - } - ); +CONTRIBUTORS + Tomas Doran (t0m) - status_bad_request - Returns a "400 BAD REQUEST" response. Takes a "message" argument as - a scalar, which will become the value of "error" in the serialized - response. + John Goulah - Example: + Christopher Laco - $self->status_bad_request( - $c, - entity => { - message => "Cannot do what you have asked!", - } - ); + Daisuke Maki - status_not_found - Returns a "404 NOT FOUND" response. Takes a "message" argument as a - scalar, which will become the value of "error" in the serialized - response. + Hans Dieter Pearcey - Example: + Brian Phillips - $self->status_not_found( - $c, - entity => { - message => "Cannot find what you were looking for!", - } - ); + Dave Rolsky -MANUAL RESPONSES - If you want to construct your responses yourself, all you need to do is - put the object you want serialized in $c->stash->{'rest'}. + Luke Saunders -SEE ALSO - Catalyst::Action::REST, Catalyst::Action::Serialize, - Catalyst::Action::Deserialize + Arthur Axel "fREW" Schmidt - For help with REST in general: + J. Shirley - The HTTP 1.1 Spec is required reading. - http://www.w3.org/Protocols/rfc2616/rfc2616.txt + Gavin Henry - Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer + Gerv http://www.gerv.net/ - The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage + Colin Newell -AUTHOR - Adam Jacob , with lots of help from mst and - jrockway + Wallace Reis - Marchex, Inc. paid me while I developed this module. - (http://www.marchex.com) +COPYRIGHT + Copyright (c) 2006-2013 the above named AUTHOR and CONTRIBUTORS LICENSE You may distribute this code under the same terms as Perl itself.