/ 
Plack-App-unAPI-0.2
River stage one • 2 direct dependents • 2 total dependents
⭐ Starred 1 GitHub stars
/ Plack::App::unAPI

NAME

Plack::App::unAPI - Serve via unAPI

VERSION

version 0.2

SYNOPSIS

use Plack::App::unAPI;

my $app1 = sub { ... };   # a PSGI application
my $app2 = sub { ... };   # another PSGI application
my $app3 = sub { ... };   # another PSGI application

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

To run this script you can simply call plackup yourscript.psgi. Then try:

http://localhost:5000/?id=abc&format=json  # calls $app1->($env);
http://localhost:5000/?id=abc&format=xml   # calls $app2->($env);
http://localhost:5000/?id=abc&format=txt   # calls $app3->($env);
http://localhost:5000/                     # returns list of formats
http://localhost:5000/?format=xml          # returns list of formats
http://localhost:5000/?id=abc              # returns list of formats

PSGI applications can be created for instance with Plack::Component or by starting with the following boilerplate:

use Plack::Request;

my $app1 = sub { 
    my $id = Plack::Request->new(shift)->param('id');

    my $obj = lookup_object( $id ); # look up object

    return $obj
        ? [ 200, [ 'Content-Type' => $type ], [ $obj ] ]
        : [ 404, [ 'Content-Type' => 'text/plain' ], [ 'not found' ] ];
};

To further facilitate such simple applications, this module exports the function wrAPI (see below). For instance if your function lookup_object either returns an XML string or undef when passed an identifier, you can add it to your unAPI server as:

xml => wrAPI( \&lookup_object => 'application/xml' );

DESCRIPTION

This implements an unAPI server as PSGI application. unAPI is a tiny HTTP API to query discretely identified objects in different formats. The basic idea of unAPI is having two HTTP GET query parameters: id to select an object, and format to select a format. If no (or no supported) format is specified, a list of formats (in XML) is returned instead.

This implementation routes the request to different PSGI applications based on a known format parameter, or sends the format list. A PSGI application is a Perl code reference or an object with a call method that gets an environment variable and returns an array reference with defined structure as HTTP response.

METHODS

new ( %formats [, _ => { %options } ] )

To create a server object you must provide a list of mappings between format names and PSGI applications to serve requests for the particular format. 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 ]

The following information fields are supported:

docs

An URL of a document that describes the format

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.

unAPI ( %formats )

The unAPI keyword as constructor alias is exported by default. To prevent exporting, include this module via use Plack::App::unAPI ();.

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.

formats ( [ $id [, $header ] ] )

Returns a PSGI response with status 300 (Multiple Choices) and an XML document that lists all formats. The optional header argument has default value <?xml version="1.0" encoding="UTF-8"?>.

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 Voss

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Jakob Voss.

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