view release on metacpan or  search on metacpan

lib/Catalyst/Controller/REST.pm  view on Meta::CPAN

=item * C<text/xml> => C<XML::Simple>

Uses L<XML::Simple> to generate XML output.  This is probably not suitable
for any real heavy XML work. Due to L<XML::Simple>s requirement that the data
you serialize be a HASHREF, we transform outgoing data to be in the form of:

  { data => $yourdata }

=item * L<View>

Uses a regular Catalyst view.  For example, if you wanted to have your
C<text/html> and C<text/xml> views rendered by TT, set:

  __PACKAGE__->config(
      map => {
          'text/html' => [ 'View', 'TT' ],
          'text/xml'  => [ 'View', 'XML' ],
      }
  );

Your views should have a C<process> method like this:

  sub process {
      my ( $self, $c, $stash_key ) = @_;

      my $output;
      eval {
          $output = $self->serialize( $c->stash->{$stash_key} );
      };
      return $@ if $@;

      $c->response->body( $output );
      return 1;  # important
  }

  sub serialize {
      my ( $self, $data ) = @_;

      my $serialized = ... process $data here ...

      return $serialized;
  }

=item * Callback

For infinite flexibility, you can provide a callback for the
deserialization/serialization steps.

  __PACKAGE__->config(
      map => {
          'text/xml'  => [ 'Callback', { deserialize => \&parse_xml, serialize => \&render_xml } ],
      }
  );

The C<deserialize> callback is passed a string that is the body of the
request and is expected to return a scalar value that results from
the deserialization.  The C<serialize> callback is passed the data
structure that needs to be serialized and must return a string suitable
for returning in the HTTP response.  In addition to receiving the scalar
to act on, both callbacks are passed the controller object and the context
(i.e. C<$c>) as the second and third arguments.

=back

By default, L<Catalyst::Controller::REST> will return a
C<415 Unsupported Media Type> response if an attempt to use an unsupported
content-type is made.  You can ensure that something is always returned by
setting the C<default> config option:

  __PACKAGE__->config(default => 'text/x-yaml');

would make it always fall back to the serializer plugin defined for
C<text/x-yaml>.

=head1 CUSTOM SERIALIZERS

Implementing new Serialization formats is easy!  Contributions
are most welcome!  If you would like to implement a custom serializer,
you should create two new modules in the L<Catalyst::Action::Serialize>
and L<Catalyst::Action::Deserialize> namespace.  Then assign your new
class to the content-type's you want, and you're done.

See L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>
for more information.

=head1 STATUS HELPERS

Since so much of REST is in using HTTP, we provide these Status Helpers.
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<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.

=over

=cut

BEGIN { extends 'Catalyst::Controller' }
use Params::Validate qw(SCALAR OBJECT);

__PACKAGE__->mk_accessors(qw(serialize));

__PACKAGE__->config(
    'stash_key' => 'rest',
    'map'       => {
        'text/xml'           => 'XML::Simple',
        'application/json'   => 'JSON',
        'text/x-json'        => 'JSON',
    },
    'compliance_mode' => 0,
);

sub begin : ActionClass('Deserialize') { }

sub end : ActionClass('Serialize') { }

=item status_ok