NAME

Plack::App::unAPI - Serve via unAPI

VERSION

version 0.61

SYNOPSIS

Create app.psgi like this:

    use Plack::App::unAPI;

    my $get_json = sub { my $id = shift; ...; return $json; };
    my $get_xml  = sub { my $id = shift; ...; return $xml; };
    my $get_txt  = sub { my $id = shift; ...; return $txt; };

    unAPI
        json => wrAPI( $get_json => 'application/json' ),
        xml  => wrAPI( $get_xml  => 'application/xml' ),
        txt  => wrAPI( $get_txt  => 'text/plain', docs => 'http://example.com' );

The function wrAPI facilitates definition of PSGI apps that serve resources in one format, based on HTTP query parameter id. One can also use custom PSGI apps:

    use Plack::App::unAPI;

    my $app1 = sub { ... };   # PSGI app that serves resource in JSON
    my $app2 = sub { ... };   # PSGI app that serves resource in XML
    my $app3 = sub { ... };   # PSGI app that serves resource in plain text

    unAPI
        json => [ $app1 => 'application/json' ],
        xml  => [ $app2 => 'application/xml' ],
        txt  => [ $app3 => 'text/plain', docs => 'http://example.com' ];

One can also implement the unAPI Server as subclass of Plack::App::unAPI:

    package MyUnAPIServer;
    use parent 'Plack::App::unAPI';

    our $formats = {
            json => [ 'application/json' ],
            xml  => [ 'application/xml' ],
            txt  => [ 'text/plain', docs => 'http://example.com' ]
        };
    
    sub format_json { my $id = $_[1]; ...; return $json; }
    sub format_xml  { my $id = $_[1]; ...; return $xml; }
    sub format_txt  { my $id = $_[1]; ...; return $txt; }

DESCRIPTION

Plack::App::unAPI implements an unAPI server as PSGI application. The HTTP request is routed to different PSGI applications based on the requested format. An unAPI server receives two query parameters via HTTP GET:

id

a resource identifier to select the resource to be returned.

format

a format identifier. If no (or no supported) format is specified, a list of supported formats is returned as XML document.

METHODS

unAPI ( %formats )

Exported by default as handy alias for

    Plack::App::unAPI->new( formats => \%formats )->to_app

wrAPI ( $code, $type, [ %about ] )

This method returns an array reference to be passed to the constructor. The first argument must be a simple code reference that gets called with id as only parameter. If its return value is undef, a 404 response is returned. Otherwise the code reference must return a serialized byte string (NO unicode characters) that has MIME type $type. To give an example:

    sub get_json { my $id = shift; ...; return $json; }

    # short form:
    my $app = wrAPI( \&get_json => 'application/json' );

    # equivalent code:
    my $app = [
        sub {
            my $id   = Plack::Request->new(shift)->param('id') // '';
            my $json = get_json( $id );
            return defined $json
                ? [ 200, [ 'Content-Type' => $type ], [ $json ] ]
                : [ 404, [ 'Content-Type' => 'text/plain' ], [ 'not found' ] ];
        } => 'application/json' 
    ];

CONFIGURATION

formats

Hash reference that maps format names to PSGI applications. Each application is wrapped in an array reference, followed by its MIME type and optional information fields about the format. So the general form is:

    $format => [ $app => $type, %about ]

If a class implements method 'format_$format' this form is also possible:

    $format => [ $type, %about ]

The following optional information fields are supported:

docs

An URL of a document that describes the format

always

By default, the format list with HTTP status code 300 is returned if unless both, format and id have been supplied. If 'always' is set to true, an empty identifier will also be routed to the format's application.

quality

A number between 0.000 and 1.000 that describes the "source quality" for content negotiation. The default value is 1.

encoding

One or more content encodings, for content negotiation. Typical values are gzip or compress.

charset

The charset for content negotiation (undef by default).

language

One or more languages for content negotiation (undef by default).

General options for all formats can be passed with the _ field (no format can have the name _).

By default, the result is checked to be valid PSGI (at least to some degree) and errors in single applications are catched - in this case a response with HTTP status code 500 is returned.

FUNCTIONS

SEE ALSO

• http://unapi.info

• Chudnov et al. (2006): Introducing unAP. In: Ariadne, 48, <http://www.ariadne.ac.uk/issue48/chudnov-et-al/>.

AUTHOR

Jakob Voß

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Jakob Voß.

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

cpanm Plack::App::unAPI

perl -MCPAN -e shell
install Plack::App::unAPI