NAME

       Jifty::API - Manages and allow reflection on the Jifty::Actions that make up a Jifty
       application's API

SYNOPSIS

        # Find the full name of an action
        my $class = Jifty->api->qualify('SomeAction');

        # New users cannot run some actions
        if (Jifty->web->current_user->age < 18) {
            Jifty->api->deny(qr/Vote|PurchaseTobacco/);
        }

        # Some users cannot even see some actions
        if (Jifty->web->current_user->id > 10) {
            Jifty->api->hide('Foo');
            Jifty->api->show('FooBar');
            Jifty->api->hide('FooBarDeleteTheWorld');
        }

        # Fetch the class names of all actions
        my @actions = Jifty->api->all_actions;

        # Fetch the class names of all the allowed actions
        my @allowed = Jifty->api->actions;

        # Fetch all of the visible actions (some of which may not be allowed)
        my @visible = Jifty->api->visible_actions;

        # Check to see if an action is allowed
        if (Jifty->api->is_allowed('TrueFooBar')) {
            # do something...
        }

        # Check to see if an action is visible
        if (Jifty->api->is_visible('SpamOurUsers')) {
            SpamBot->be_annoying;
        }

        # Undo all allow/deny/restrict/hide calls
        Jifty->api->reset;

DESCRIPTION

       You can fetch an instance of this class by calling "api" in Jifty in your application.
       This object can be used to examine the actions available within your application and
       manage access to those actions.

METHODS

   new
       Creates a new "Jifty::API" object.

       Don't use this, see "api" in Jifty to access a reference to "Jifty::API" in your
       application.

   qualify ACTIONNAME
       Returns the fully qualified package name for the given provided action.  If the
       "ACTIONNAME" starts with "Jifty::" or "ApplicationClass::Action", simply returns the given
       name; otherwise, it prefixes it with the "ApplicationClass::Action".

   reset
       Resets which actions are allowed to the defaults; that is, all of the application's
       actions, Jifty::Action::AboutMe, Jifty::Action::Autocomplete, and Jifty::Action::Redirect
       are allowed and visible; everything else is denied and hidden. See "restrict" for the
       details of how limits are processed.

   deny_for_get
       Denies all actions except Jifty::Action::AboutMe, Jifty::Action::Autocomplete and
       Jifty::Action::Redirect. This is to protect against a common cross-site scripting hole. In
       your "before" dispatcher rules, you can whitelist actions that are known to be read-only.

       This is called automatically during any "GET" request.

   allow RESTRICTIONS
       Takes a list of strings or regular expressions, and adds them in order to the list of
       limits for the purposes of "is_allowed".  See "restrict" for the details of how limits are
       processed.

       Allowing actions also "show" them.

   deny RESTRICTIONS
       Takes a list of strings or regular expressions, and adds them in order to the list of
       limits for the purposes of "is_allowed".  See "restrict" for the details of how limits are
       processed.

   hide RESTRICTIONS
       Takes a list of strings or regular expressions, and adds them in order to the list of
       limits for the purposes of "is_visible".  See "restrict" for the details of how limits are
       processed.

       Hiding actions also "deny" them.

   show RESTRICTIONS
       Takes a list of strings or regular expressions, and adds them in order to the list of
       limits for the purposes of "is_visible".  See "restrict" for the details of how limits are
       processed.

   restrict POLARITY RESTRICTIONS
       Method that "allow", "deny", "hide", and "show" call internally; POLARITY is one of
       "allow", "deny", "hide", or "show". Limits are evaluated in the order they're called. The
       last limit that applies will be the one which takes effect. Regexes are matched against
       the class; strings are fully /qualify and used as an exact match against the class name.
       The base set of restrictions (which is reset every request) is set in "reset", and usually
       modified by the application's Jifty::Dispatcher if need be.

       If you call:

           Jifty->api->deny  ( qr'Foo' );
           Jifty->api->allow ( qr'FooBar' );
           Jifty->api->deny  ( qr'FooBarDeleteTheWorld' );

       ..then:

           calls to MyApp::Action::Baz will succeed.
           calls to MyApp::Action::Foo will fail.
           calls to MyApp::Action::FooBar will pass.
           calls to MyApp::Action::TrueFoo will fail.
           calls to MyApp::Action::TrueFooBar will pass.
           calls to MyApp::Action::TrueFooBarDeleteTheWorld will fail.
           calls to MyApp::Action::FooBarDeleteTheWorld will fail.

   is_allowed CLASS
       Returns true if the CLASS name (which is fully qualified if it is not already) is allowed
       to be executed.  See "restrict" above for the rules that the class name must pass.

   is_visible CLASS
       Returns true if the CLASS name (which is fully qualified if it is not already) is allowed
       to be seen.  See "restrict" above for the rules that the class name must pass.

   decide_action_polarity CLASS, ALLOW, DENY
       Returns true if the CLASS name it has the ALLOW restriction, false if it has the DENY
       restriction. This is a helper method used by "is_allowed" and "is_visible".

       If no restrictions apply to this action, then false will be returned.

   explain CLASS
       Returns a string describing what allow, deny, show, and hide rules apply to the class
       name.

   all_actions
       Lists the class names of all actions for this Jifty application, regardless of which are
       allowed or hidden.  See also "actions" and "visible_actions".

   actions
       Lists the class names of all of the allowed actions for this Jifty application; this may
       include actions under the "Jifty::Action::" namespace, in addition to your application's
       actions.  See also "all_actions" and "visible_actions".

   visible_actions
       Lists the class names of all of the visible actions for this Jifty application; this may
       include actions under the "Jifty::Action::" namespace, in addition to your application's
       actions.  See also "all_actions" and "actions".

SEE ALSO

       Jifty, Jifty::Web, Jifty::Action

LICENSE

       Jifty is Copyright 2005-2010 Best Practical Solutions, LLC.  Jifty is distributed under
       the same terms as Perl itself.