r44@latte: adam | 2006-12-01 00:12:17 -0800

[catagits/Catalyst-Action-REST.git] / README

NAME
    Catalyst::Controller::REST - A RESTful controller

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 ..
        }

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:

          $self->status_ok(
            $c, 
            entity => {
                radiohead => "Is a good band!",
            }
          );

    status_created
        Returns a "201 CREATED" response. Takes an "entity" to serialize,
        and a "location" where the created object can be found.

        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.

    status_accepted
        Returns a "202 ACCEPTED" response. Takes an "entity" to serialize.

        Example:

          $self->status_accepted(
            $c, 
            entity => {
                status => "queued",
            }
          );

    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.

        Example:

          $self->status_bad_request(
            $c, 
            entity => {
                message => "Cannot do what you have asked!",
            }
          );

    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.

        Example:

          $self->status_not_found(
            $c, 
            entity => {
                message => "Cannot find what you were looking for!",
            }
          );

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'}.

SEE ALSO
    Catalyst::Action::REST, Catalyst::Action::Serialize,
    Catalyst::Action::Deserialize

    For help with REST in general:

    The HTTP 1.1 Spec is required reading.
    http://www.w3.org/Protocols/rfc2616/rfc2616.txt

    Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer

    The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage

AUTHOR
    Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and
    jrockway

    Marchex, Inc. paid me while I developed this module.
    (http://www.marchex.com)

LICENSE
    You may distribute this code under the same terms as Perl itself.