NAME

REST::Application - A framework for building RESTful web-applications.

CAVEAT

This software is still pretty young. I've been using it everyday for about 6 months in its current form and so I know it scratches my itch. It hasn't been vetted by many people though. The documentation in particular is in a flux, but should mostly be accurated.

Suggestions for improvements are welcome.

SYNOPSIS

    # not done yet

DESCRIPTION

This module was modeled after CGI::Application. If you've used that module then what you find here will be familiar.

This module acts as a base class for applications which implement a RESTful interface. As currently designed this class can handle one HTTP request per instance. When an HTTP request is recieved some dispatching logic in REST::Application is invoked, calling different handlers based on what the kind of HTTP request is was (i.e. GET, PUT, etc) and what resource it was trying to access.

This module won't ensure that your API is RESTful but hopefully it will aid in developing a REST API.

OVERVIEW

The following list describes the basic way this module is intended to be used. It does not capture everything the module can do.

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 the getResource() 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, the child 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
    

that .cgi is unRESTful.

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

The REST::Application base class provides a good number of methods, each of which can be overloaded. By default you only need to overload the setup() method but you may wish to overload others. To help with this the following outline is the calling order of the various methods in the base class. You can find detailed descriptions of each method in the METHODS section of this document.

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()
            callHandler()
                _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

REST::Application new(%args)

This method creates a new REST::Application object and returns it. The arguments passed in via %args, if any, are passed untouched to the setup() method.

CGI query([$newCGI])

This accessor/mutator retrieves the current CGI query object or sets it if one is passed in.

void defaultQueryObject([$newCGI])

This method retrieves/sets the default query object. This method is called if query() is called for the first time and no query object has been set yet.

HashRef resourceHooks([HashRef $ref | Hash %hash])

This method is used to set the resource hooks. A REST::Application hook is a regex to handler mapping. The hooks are passed in as a hash (or a reference to one) and the keys are treated as regular expressions while the values are treated as handlers should PATH_INFO match the regex that maps to that handler. The rules for handlers are as follow:

    If the handler' type is ...

        string - The handler is considered to be a method on the current
                 REST::Application instance.
        code ref - The code ref is considered to be the handler.
        object ref - The object is considered to have a getResource() method,
                     which will be used.
        array ref - The array is expected to be two elements long, the first
                    element is a class name or object instance.  The 2nd element is a method
                    name on that class/instance.
        hash ref - The current REQUEST_METHOD is used as a key to the hash, the
                   value should be one the four above handler types.

The return value of a reference is expected to be a string, which REST::Application will then send to the browser with the sendRepresentation() method.

If no argument is supplied to resourceHooks() then the current set of hooks is returned. The returned hash referces is a tied IxHash, so the keys are kept sorted.

See the EXAMPLES for more detail.

Scalar loadResource(String $path])

This method will take the value of PATH_INFO, iterate through the path regex's set in resourceHooks() and if it finds a match call the associated handler and return the handler's value, which should be a scalar. If $path is passed in then that is used instead of PATH_INFO.

String run(void)

This method calls loadResource() with no arguments and then takes that output and sends it to the remote client. Headers are sent with sendHeaders() and the representation is sent with sendRepresentation().

If the environment variable REST_APP_RETURN_ONLY is set then output isn't sent to the client. The return value of this method is the text output it sends (or would've sent).

String sendHeaders(void)

This method returns the headers as a string.

String sendRepresentation(Scalar $representation)

This method just returns $representation. It is provided soely for overloading purposes.

String headerType([String $type])

This accessor/mutator controls the type of header to be returned. This method returns one of "header, redirect, or none." If $type is passed in then that is used to set the header type.

Hash header([Hash %args])

This accessor/mutator controls the header values sent. If called without arguments then it simply returns the current header values as a hash, where the keys are the header fields and the values are the header field values.

If this method is called multiple times then the values of %args are additive. So calling $self->header(-type => "text/html") and $self->headeR(-foo => "bar") results in both the content-type field being set and the "foo" field being set.

Hash resetHeader(void)

This header causes the current header values to be reset. The previous values are returned.

Scalar defaultResourceHandler(void)

This method is called by loadResource() if no regex in resourceHooks() matches the current PATH_INFO. It returns undef by default, it exists for overloading.

AUTHORS

Matthew O'Connor <matthew@canonical.org<gt>

LICENSE

This program is free software. It is subject to the same license as Perl itself.

SEE ALSO

CGI, CGI::Application, Tie::IxHash, Carp, UNIVERSAL

cpanm REST::Application

perl -MCPAN -e shell
install REST::Application