NAME

Catalyst::Plugin::AtomServer - Atom API server for Catalyst applications

SYNOPSIS

use Catalyst qw( AtomServer
                 Authentication
                 Authentication::Credential::Atom
                 Authentication::Store::Minimal
               );

DESCRIPTION

Catalyst::Plugin::AtomServer implements the necessary bits to make it easy to build an Atom API server for any Catalyst-based application.

It implements:

• Simple XML Views

  Catalyst::View::Atom::XML provides a base view class that your application can subclass can use to provide a simple view. Given an XML::Atom-based class in $c-<stash->{xml_atom_object}, it will automatically serialize the object to XML and set the appropriate response headers.

• Request Extensions

  Catalyst::Plugin::AtomServer extends the Catalyst::Request object to add a couple of useful methods:

  • $req->is_atom

    Once you know that a particular request is an Atom request, your Catalyst handler should set is_atom to 1, like so:

    $c->request->is_atom(1);

  • $req->url_parameters

    Atom servers often implement parametrized requests in the path_info portion of the request URI. These parameters will be automatically split up into the url_parameters hash reference. For example, the URI

    /base/foo=bar/baz=quux/

    would be split into the hash reference

    {
        foo => 'bar',
        baz => 'quux',
    }

  • $req->body_parsed

    A parsed XML document containing the Atom portion of the request (the entire request content in the case of a REST request, and only the Atom portion of a SOAP request).

    You can pass this in directly to initialize an XML::Atom-based object. For example:

    my $entry = XML::Atom::Entry->new( Doc => $req->body_parsed );

• Authentication

  Catalyst::Plugin::Authentication::Credential::Atom provides support for Basic and WSSE authentication using an Atom envelope. WSSE is supported using either SOAP or REST, and Basic is supported in REST only.

• REST and SOAP interfaces

  The Atom API supports either a REST interface or a SOAP interface using a document-literal SOAP envelope. Catalyst::Plugin::AtomServer supports both interfaces, transparently for your application.

• Error Handling

  Catalyst::Plugin::AtomServer will automatically catch any exceptions thrown by your application, and it will wrap the exception in the proper response expected by an Atom client.

EXAMPLE

Below is an example server that implements authentication, dispatching, and views.

package My::App;
use strict;

use Catalyst qw( AtomServer
                 Authentication
                 Authentication::Credential::Atom
                 Authentication::Store::Minimal
               );
use My::App::View::XML;
use XML::Atom::Feed;

__PACKAGE__->config(
    name => 'MyApp',
    authentication => { users => { foo => { password => 'bar' } } },
);

__PACKAGE__->setup;

sub default : Private {
    my($self, $c) = @_;
    $c->request->is_atom(1);
    my $method = $c->request->method;
    if ($method eq 'GET') {
        $c->forward('get_entries');
    }
}

sub get_entries : Private {
    my($self, $c) = @_;

    ## Authenticate the user using WSSE or Basic auth.
    $c->login_atom or die "Unauthenticated";

    my $feed = XML::Atom::Feed->new;
    $feed->title('Blog');
    $c->stash->{xml_atom_object} = $feed;
}

sub end : Private {
    my($self, $c) = @_;
    $c->forward('My::App::View::XML');
}

package My::App::View::XML;
use base qw( Catalyst::View::Atom::XML );

SEE ALSO

XML::Atom, Catalyst

AUTHOR

Six Apart, cpan@sixapart.com

LICENSE

Catalyst::Plugin::AtomServer is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR & COPYRIGHT

Except where otherwise noted, Catalyst::Plugin::AtomServer is Copyright 2006 Six Apart, cpan@sixapart.com. All rights reserved.