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 );

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.

CPAN RT