X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README;h=ad0360158eee4678e2e68c2e6c2b179982bafe49;hb=63d41fcd068cf0363892abd53d5b5bd892d985d8;hp=f7175e251ba3a492dadce69cc47fa7ae6ecbf043;hpb=01f9819aaf3c33459ffb2c9005a32ad59eee8663;p=catagits%2FCatalyst-Action-REST.git diff --git a/README b/README index f7175e2..ad03601 100644 --- a/README +++ b/README @@ -1,176 +1,99 @@ NAME - Catalyst::Controller::REST - A RESTful controller + Catalyst::Action::REST - Automated REST Method Dispatching 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', - }, - ); + sub foo :Local :ActionClass('REST') { + ... do setup for HTTP method specific handlers ... } - # Answer PUT requests to "thing" - sub thing_PUT { - .. some action .. + sub foo_GET { + ... do something for GET requests ... } -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. + # alternatively use an Action + sub foo_PUT : Action { + ... do something for PUT requests ... + } - Example: +DESCRIPTION + This Action handles doing automatic method dispatching for REST + requests. It takes a normal Catalyst action, and changes the dispatch to + append an underscore and method name. First it will try dispatching to + an action with the generated name, and failing that it will try to + dispatch to a regular method. - $self->status_ok( - $c, - entity => { - radiohead => "Is a good band!", - } - ); + For example, in the synopsis above, calling GET on "/foo" would result + in the foo_GET method being dispatched. - status_created - Returns a "201 CREATED" response. Takes an "entity" to serialize, - and a "location" where the created object can be found. + If a method is requested that is not implemented, this action will + return a status 405 (Method Not Found). It will populate the "Allow" + header with the list of implemented request methods. You can override + this behavior by implementing a custom 405 handler like so: - Example: + sub foo_not_implemented { + ... handle not implemented methods ... + } - $self->status_created( - $c, - location => $c->req->uri->as_string, - entity => { - radiohead => "Is a good band!", - } - ); + If you do not provide an _OPTIONS subroutine, we will automatically + respond with a 200 OK. The "Allow" header will be populated with the + list of implemented request methods. - In the above example, we use the requested URI as our location. This - is probably what you want for most PUT requests. + It is likely that you really want to look at Catalyst::Controller::REST, + which brings this class together with automatic Serialization of + requests and responses. - status_accepted - Returns a "202 ACCEPTED" response. Takes an "entity" to serialize. + When you use this module, the request class will be changed to + Catalyst::Request::REST. - Example: +METHODS + dispatch + This method overrides the default dispatch mechanism to the + re-dispatching mechanism described above. - $self->status_accepted( - $c, - entity => { - status => "queued", - } - ); +SEE ALSO + You likely want to look at Catalyst::Controller::REST, which implements + a sensible set of defaults for a controller doing REST. - 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. + Catalyst::Action::Serialize, Catalyst::Action::Deserialize - Example: +TROUBLESHOOTING + Q: I'm getting a "415 Unsupported Media Type" error. What gives?! + A: Most likely, you haven't set Content-type equal to + "application/json", or one of the accepted return formats. You can + do this by setting it in your query accepted return formats. You can + do this by setting it in your query string thusly: + "?content-type=application%2Fjson (where %2F == / uri escaped)." - $self->status_bad_request( - $c, - entity => { - message => "Cannot do what you have asked!", - } - ); + NOTE Apache will refuse %2F unless configured otherwise. Make sure + "AllowEncodedSlashes On" is in your httpd.conf file in order for + this to run smoothly. - 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. +AUTHOR + Adam Jacob , with lots of help from mst and + jrockway - Example: + Marchex, Inc. paid me while I developed this module. + () - $self->status_not_found( - $c, - entity => { - message => "Cannot find what you were looking for!", - } - ); +CONTRIBUTORS + Arthur Axel "fREW" Schmidt -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'}. + Christopher Laco -SEE ALSO - Catalyst::Action::REST, Catalyst::Action::Serialize, - Catalyst::Action::Deserialize + Luke Saunders - For help with REST in general: + John Goulah - The HTTP 1.1 Spec is required reading. - http://www.w3.org/Protocols/rfc2616/rfc2616.txt + Daisuke Maki - Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer + J. Shirley - The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage + Hans Dieter Pearcey -AUTHOR - Adam Jacob , with lots of help from mst and - jrockway + Tomas Doran (t0m) - Marchex, Inc. paid me while I developed this module. - (http://www.marchex.com) +COPYRIGHT + Copyright the above named AUTHOR and CONTRIBUTORS LICENSE You may distribute this code under the same terms as Perl itself.