Plack::App::unAPI - Serve via unAPI
version 0.31
Create <app.psgi> like this:
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' ];
Run for instance by calling plackup yourscript.psgi and retrieve:
plackup yourscript.psgi
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 as subclass of Plack::Component or as simple code reference:
use Plack::Request; # PSGI application that serves resource in JSON sub get_resource_as_json { my $id = shift; ... return $json; } my $app1 = sub { my $id = Plack::Request->new(shift)->param('id') // ''; my $json = get_resource_as_json( $id ); return defined $json ? [ 200, [ 'Content-Type' => $type ], [ $json ] ] : [ 404, [ 'Content-Type' => 'text/plain' ], [ 'not found' ] ]; };
To facilitate applications as above, Plack::App::unAPI exports the function wrAPI which can be used like this:
wrAPI
use Plack::App::unAPI; unAPI json => wrAPI( \&get_resource_as_json => 'application/json' ), xml => wrAPI( \&get_resource_as_xml => 'application/xml' ), txt => wrAPI( \&get_resource_as_plain => 'text/plain' );
Plack::App::unAPI implements an unAPI server as PSGI application. The HTTP request is routed to different PSGI applications based on the requested format.
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.
call
unAPI is a tiny HTTP API to query discretely identified resources in different formats. The basic idea of unAPI is having two HTTP GET query parameters:
id as resource identifier
format to select a format
If no (or no supported) format is specified, a list of formats is returned as XML document.
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 optional information fields are supported:
An URL of a document that describes the format
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.
A number between 0.000 and 1.000 that describes the "source quality" for content negotiation. The default value is 1.
One or more content encodings, for content negotiation. Typical values are gzip or compress.
gzip
compress
The charset for content negotiation (undef by default).
undef
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.
The unAPI keyword as constructor alias is exported by default. To prevent exporting, include this module via use Plack::App::unAPI ();.
unAPI
use Plack::App::unAPI ();
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.
id
$type
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"?>.
<?xml version="1.0" encoding="UTF-8"?>
Returns a list of content variants to be used in HTTP::Negotiate. The return value is an array reference of array references, each with seven elements: format name, source quality (qs), type, encoding, charset, language, and size. The return value for the example given above would be:
[ ['json','1','application/json',undef,undef,undef,0], ['xml','1','application/xml',undef,undef,undef,0], ['txt','1','text/plain',undef,undef,undef,0] ]
Plack::App::unAPI uses Log::Contextual. To get detailed logging messages set $ENV{PLACK_APP_UNAPI_TRACE} = 1.
$ENV{PLACK_APP_UNAPI_TRACE} = 1
Plack::Middleware::Negotiate
http://unapi.info
Chudnov et al. (2006): Introducing unAP. In: Ariadne, 48, <http://www.ariadne.ac.uk/issue48/chudnov-et-al/>.
Jakob Voss
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.
To install Plack::App::unAPI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Plack::App::unAPI
CPAN shell
perl -MCPAN -e shell install Plack::App::unAPI
For more information on module installation, please visit the detailed CPAN module installation guide.