NAME

SYNOPSIS

    # MyRESTApp L<REST::Application> instance / mod_perl handler
    package MyRESTApp;
    use Apache;
    use Apache::Constants qw(:common);

    sub handler {
        __PACKAGE__->new(request => $r)->run();
        return OK;
    }
    
    sub getMatchText { return Apache->uri }

    sub setup {
        my $self = shift;
        $self->resourceHooks(
            qr{/rest/parts/(\d+)} => 'get_part',
            # ... other handlers here ...
        );
    }

    sub get_part {
        my ($self, $part_num) = @_;
        # Business logic to retrieve part num
    }

    # Apache conf
    <Location /rest>
        perl-script .cgi
        PerlHandler MyRESTApp
    </Location>

DESCRIPTION

OVERVIEW

1. Subclass

Subclass REST::Application, i.e. "use base 'REST::Application'".

2. Overload "setup()"

Overload the "setup()" method and set up some resource hooks with the "resourceHooks()" method. Hooks are mappings of the form:

            REGEX => handler
    

where handler is either a method name, a code reference, an object which supports a method with the same name as the HTTP method (or "getResource" if no such method), or a reference to an array of the form: "[$objectRef, "methodName"]" ($objectRef can be a class name instead).

The regular expressions are applied, by default, to the path info of the HTTP request. Anything captured by parens in the regex will be passed into the handler as arguments.

For example:

    qr{/parts/(\d+)$} => "getPartByNumber",
    

The above hook will call a method named "getPartByNumber" on the current object (i.e. $self, an instance of REST::Application) if the path info of the requested URI matches the above regular expression. The first argument to the method will be the part number, since that's the first element captured in the regular expression.

3. Write code.

Write the code for the handler specified above. So here we'd define the "getPartByNumber" method.

4. Create a handler/loader.

Create an Apache handler, for example:

    use MyRESTApp;
    sub handler {
        my $r = shift;
        my $app = MyRESTApp->new(request => $r);
        $app->run();
    }
    

or a small CGI script with the following code:

    #!/usr/bin/perl
    use MyRESTApp;
    MyRESTApp->new()->run();
    

In the second case, for a CGI script, you'll probably need to do something special to get Apache to load up your script unless you give it a .cgi extension. It would be unRESTful to allow your script to have a .cgi extension, so you should go the extra mile and configure Apache to run your script without it. For example, it'd be bad to have your users go to:

    http://www.foo.tld/parts.cgi/12345.html
    

5. Call the "run()" method.

When the "run()" method is called the path info is extracted from the HTTP request. The regexes specified in step 2 are processed, in order, and if one matches then the handler is called. If the regex had paren. matching then the matched elements are passed into the handler. A handler is also passed a copy of the REST::Application object instance (except for the case when the handler is a method on the REST::Application object, in that case it'd be redundant). So, when writing a subroutine handler you'd do:

            sub rest_handler {
                my ($rest, @capturedArgs) = @_;
                ...
            }
    

6. Return a representation of the resource.

The handler is processed and should return a string or a scalar reference to a string. Optionally the handler should set any header information via the "header()" method on instance object pased in.

CALLING ORDER

If a method is followed by the string NOOP then that means it does nothing by default and it exists only to be overloaded.

    new()
        setup() - NOOP
    run()
        preRun() - NOOP
        loadResource()
            getMatchText()
                getPathInfo()
                    query()
                        defaultQueryObject()
            defaultResourceHandler() - NOOP
            resourceHooks()
            checkMatch()
                _setLastRegexMatches()
            _getHandlerFromHook()
                resourceHooks()
                defaultResourceHandler() - NOOP
                getRequestMethod()
                    query()
                        defaultQueryObject()
                bestContentType()
                    simpleContentNegotiation
                        getContentPrefs
                            getAcceptHeader
                        scoreType()
            callHandler()
                getHandlerArgs
                    _getLastRegexMatches()
                    extraHandlerArgs()
                preHandler() - NOOP
                ... your handler called here ...
                postHandler() - NOOP
        postRun() - NOOP
        getHeaders()
            headerType()
            query()
                defaultQueryObject()
            header()
        addRepresentation()

The only methods not called as part of the new() or run() methods are the helper methods "resetHeader()" and "setRedirect()", both of which call the "header()" and "headerType()" methods.

For example, if you wanted to have your code branch on the entire URI of the HTTP request rather than just the path info you'd merely overload "getMatchText()" to return the URI rather than the path info.

METHODS

AUTHORS

LICENSE

SEE ALSO

POD ERRORS

Around line 550:

Nested L<> are illegal. Pretending inner one is X<...> so can continue looking for other errors.

Around line 645:

You forgot a '=back' before '=head1'

Around line 704:

=back without =over