NAME
    CatalystX::SimpleAPI - Simple API support for Catalyst apps

SYNOPSIS
        package ServiceApp::Controller::API;

        use Moose;
        use namespace::autoclean;
        BEGIN { extends 'Catalyst::Controller' }

        with 'CatalystX::Controller::SimpleAPI';

        __PACKAGE__->config(
            authkeys => {
                'AE281S228D4' => {
                    ip_check => '^10\.0\.0\.[0-9]+$',
                    valid_applications => 'myapp',
                },
            },
        );

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

            # will return false if the api did not pass authorization.
            return $self->prepare_api_request($c);
        }

        sub foo : Local {
            my ( $self, $c ) = @_;
            $c->stash(
                api_response => {
                    processed => 1,
                    status => 'success',
                    data => {
                        results => $c->req->params,
                    }
                },
            );
        }

        1;

        ...

        package MyApp::Model::ServiceApp; 

        use Moose;
        use namespace::autoclean;

        extends 'Catalyst::Model';

        with 'SimpleAPI::Agent';

        __PACKAGE__->config(
            api_key => 'AE281S228D4',
            application_id => 'myapp',
            api_base_url => 'http://localhost:5000/'
        );

        1;

        ...

        $c->model('ServiceApp')->request('/api/foo', { value => 10 });

DESCRIPTION
    It provides a simple API support - currently only JSON based - for
    Catalyst applications.

USAGE
    In your actions, all your API arguments will have already been placed in
    "$c->stash->{'api_params'}". Your API response will be placed in
    "$c->stash->{'api_response'}". The "api_response" hash should have the
    following structure.

        $c->stash->{'api_response'} = {
            # true / false value indicating the request was processed.
            processed => 0,

            # 'success' or 'failed' indicating whether the request was processed
            # successfully.
            status => 'failed',
    
            # hashref containing the results of the api action
            data => {},

            # error messages in the form of field => 'message' in the case of an error
            errors => {
                # 'general' should always be present to describe the overall error
                general => 'failed validation',

                # per-parameter error messaging if appropriate.
                ingredient => 'Ingredient is invalid.',
            },
        };

    If you process your request, you should set "processed" to 1 even if the
    request was did not have a successful result. The "processed" value is
    used to indicate that the parameters were accepted and the action
    requested was attempted. The "status" value is used to indicate whether
    the requested action accomplished what was requested. The basic rule of
    thumb here is that "processed" should only be set to 0 if the action
    could not be started for some reason (such as auth failure or other
    exceptional condition.) Note that if "processed" is 0, "status" will
    ALWAYS be failed.

    In your subclass, you will need to call the
    "$self->prepare_api_request($c)" method to initialize the API request.
    This is usually done in the "auto" action or the root of the action
    chain.

SEE ALSO
    Catalyst Advent Calendar 2009
    <http://www.catalystframework.org/calendar/2009/21>

AUTHOR
    Jay Kuri (jayk) "<jayk@cpan.org>".

CONTRIBUTORS
    Wallace Reis (wreis) "<wreis@cpan.org>".

SPONSORSHIP
    Development sponsored by Ionzero LLC <http://www.ionzero.com/>.

COPYRIGHT & LICENSE
    Copyright (C) 2010 Jay Kuri and the above contributors.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.