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.