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 <adam@stalecoffee.org>, with lots of help from mst and
+ jrockway
- Example:
+ Marchex, Inc. paid me while I developed this module.
+ (<http://www.marchex.com>)
- $self->status_accepted(
- $c,
- entity => {
- status => "queued",
- }
- );
+CONTRIBUTORS
+ Tomas Doran (t0m) <bobtfish@bobtfish.net>
- 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 <daisuke@endeworks.jp>
- 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 <bphillips@cpan.org>
- $self->status_not_found(
- $c,
- entity => {
- message => "Cannot find what you were looking for!",
- }
- );
+ Dave Rolsky <autarch@urth.org>
-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 <frioux@gmail.com>
- For help with REST in general:
+ J. Shirley <jshirley@gmail.com>
- The HTTP 1.1 Spec is required reading.
- http://www.w3.org/Protocols/rfc2616/rfc2616.txt
+ Gavin Henry <ghenry@surevoip.co.uk>
- 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 <colin@opusvl.com>
-AUTHOR
- Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and
- jrockway
+ Wallace Reis <wreis@cpan.org>
- 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.
projects / catagits/Catalyst-Action-Serialize-Data-Serializer.git / blobdiff