NAME

WWW::REST::Apid - Generic REST API Module

SYNOPSIS

 use WWW::REST::Apid;
 use Authen::Simple::LDAP;
 
 my $server = WWW::REST::Apid->new(
  host => 'localhost',
  port => 8080,
  apiname => 'my api',
  apiversion => '1.0',
  authbasic => 1,
  sublogin => sub { 
                     my($user, $pass) = @_;
                     my $ldap = Authen::Simple::LDAP->new( 
                     host    => 'ldap.company.com',
                     basedn  => 'ou=People,dc=company,dc=net'
                   );
                   if ( $ldap->authenticate( $user, $pass ) ) {
                     return 1; # ok
                   }
                   return 0; # fail
                 },
  log => sub { my $msg = shift; syslog('info', $msg); },
  foreground => 0,
 );
 
 $server->mapuri(path => '/', doauth => 1, handler => sub { return { msg => 'ok' } });
 
 $server->run();

DESCRIPTION

The WWW::REST::Apid module can be used to implement a REST API for almost anything.

If you want fast and easy results, please try the apid daemon, which is shipped with the WWW::REST::Apid distribution, first.

METHODS

new

The new method returns a new WWW::REST::Apid object. All parameters are optional and will be preset with reasonable defaults.

Supported parameters:

host

The hostname or ip address where the daemon will listen to. Default: 'localhost'.

port

The TCP port to use. Default: 8080.

apiname

The name of your API.

apiversion

The version of your API.

authbasic

Use HTTP Basic Authentication. The parameter defines the realm.

authuri

Use HTTP POST Authentication with login uri redirect for unauthenticated users.

sublogin

Expects a closure as parameter. The closure gets two parameters supplied during the login process: the username and the password supplied by the client in clear text.

If authentication shall succeed, return 1, otherwise 0.

Default: returns always false.

log

Logging function to use, expects a closure as parameter. One parameter will be given to the closure: the log message. Put it where ever you want.

Default: ignore.

foreground

If set to true, the daemon doesn't fork a child process for new incoming connections, which it does otherwise. If you work with a preforking system as Any::Daemon::HTTP, then set it to true. If you use something like Generic::Daemon, set it to false.

Default: false.

sslcrt AND sslkey

If both are given, files are expected. sslcrt must be a X509 PEM encoded SSL certificate, sslkey must be a PEM encoded SSL unencrypted private key for the certificate.

IO::Socket::SSL-new() parameters>

Any parameter starting with 'SSL' will be fed unaltered to IO::Socket::SSL->new().

lateconfig

Supply any of the above mentioned parameters at some later point, which allows to re-configure certain aspects of the daemon. Some variables cannot be changed once the daemon runs, especially the host and port variables.

Expects the parameters as a hash. Example:

 $server->lateconfig(authuri => '/login');

mapuri

The mapuru method is the heart of the module. It expects hash parameters.

Example:

 $server->mapuri(path => '/', doauth => 1, handler => sub { return { msg => 'ok' } });

The following parameters are supported:

path

Required: the uri path which shall be mapped to some action.

handler

Required: closure is expected as parameter. The closure gets as its only argument a hash reference supplied which contains data posted by a client (either via POST, PUT or GET query params).

It is expected to return a hash reference with results again.

JSON conversion will be done automatically.

You can access the current HTTP::Request object within the handler by using the variable $req and the HTTP::Response object with $res.

doauth

Optional: turn on authentication for this particular path.

The sublogin closure must be imlemented.

valid

Optional: a hash reference describing the input validation using the notation of Data::Validate::Struct. If defined, data posted by clients will be validated and if found to be invalid, an error will be returned.

run

Finally, start the server.

This method never returns.

AUTHOR

T.v.Dein <tlinden@cpan.org>

BUGS

Report bugs to http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-REST-Apid

SEE ALSO

apid HTTP::Daemon HTTP::Daemon::SSL Daemon::Generic Config::General Data::Validate::Struct

COPYRIGHT

Copyright (c) 2014-2017 by T.v.Dein <tlinden@cpan.org>. All rights reserved.

LICENSE

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

VERSION

apid Version 0.07.

cpanm WWW::REST::Apid

perl -MCPAN -e shell
install WWW::REST::Apid