Lemonldap::NG::Common::PSGI::Router(3pm)

1Lemonldap::NG::Common::UPsSeGrI:C:oRnoturtiebru(t3e)d PeLrelmoDnolcduampe:n:tNaGt:i:oCnommon::PSGI::Router(3)
2
3
4

NAME

6       Lemonldap::NG::Common::PSGI::Router - Base library for REST APIs of
7       Lemonldap::NG.
8

SYNOPSIS

10         package My::PSGI;
11
12         use base Lemonldap::NG::Common::PSGI::Router;
13
14         sub init {
15           my ($self,$args) = @_;
16           # Will be called 1 time during startup
17
18           # Declare REST routes (could be HTML templates or methods)
19           $self->addRoute ( 'index.html', undef, ['GET'] )
20                ->addRoute ( books => { ':book' => 'booksMethod' }, ['GET', 'POST'] )
21                ->addRoute ( properties => { '*' => 'propertiesMethod' }, ['GET', 'POST', 'PUT', 'DELETE']);
22
23           # Default route (ie: PATH_INFO == '/')
24           $self->defaultRoute('index.html');
25
26           # See Lemonldap::NG::Common::PSGI for other options
27
28           # Return a boolean. If false, then error message has to be stored in
29           # $self->error
30           return 1;
31         }
32
33         sub booksMethod {
34           my ( $self, $req, @otherPathInfo ) = @_;
35           my $book = $req->params('book');
36           my $method = $req->method;
37           ...
38           $self->sendJSONresponse(...);
39         }
40
41         sub propertiesMethod {
42           my ( $self, $property, @otherPathInfo ) = @_;
43           my $method = $req->method;
44           ...
45           $self->sendJSONresponse(...);
46         }
47
48       This package could then be called as a CGI, using FastCGI,...
49
50         #!/usr/bin/env perl
51
52         use My::PSGI;
53         use Plack::Handler::FCGI; # or Plack::Handler::CGI
54
55         Plack::Handler::FCGI->new->run( My::PSGI->run() );
56

DESCRIPTION

58       This package provides base class for Lemonldap::NG REST API but could
59       be used regardless.
60

METHODS

62       See Lemonldap::NG::Common::PSGI for logging methods, content
63       sending,...
64
65   Initialization methods
66       addRoute ( $word, $dest, $methods )
67
68       Declare a REST route. Arguments:
69
70       $word:
71           the first word of /path/info.
72
73       $dest:
74           string, sub ref or hash ref (see "Route types" below)
75
76       $methods:
77           array ref containing the methods concerned by this route.
78
79       Route types
80
81       As seen in "SYNOPSIS", you can declare routes with variable component.
82       $dest can be:
83
84       a word:
85           the name of the method to call
86
87       undef:
88           $word is used as $dest
89
90       a ref to code:
91           an anonymous subroutin to call
92
93       a hash ref:
94           it's a recursive call to `{ $word => $dest }`
95
96       an array ref:
97           in this case each element of the array will be considered as `{
98           $element => $element }`. So each element must be a word that makes
99           a correspondence between a path_info word and a subroutine
100
101       Some special $word:
102
103       ':name':
104           the word in path_info will be stored in GET parameters
105
106       '*':
107           the subroutine will be called with the word of path_info as second
108           argument (after $req)
109
110       'something.html':
111           if $word finishes with '.html', and $dest is undef, then sendHtml()
112           will be called with 'something.tpl' as template name.
113
114       Examples:
115
116       to manage http://.../books/127 with book() where 127 is the book
117       number, use:
118             $self->addRoute( books => { ':bookId' => 'book' }, ['GET'] );
119
120           bookId parameter will be stored in $req->params('bookId');
121
122       to manage http://.../books/127/pages/5 with page(), use:
123             $self->addRoute( books => { ':bookId' => { pages => { ':pageId' => 'page' } } }, ['GET'] );
124
125       to manage simultaneously the 2 previous examples
126             $self->addRoute( books => { ':bookId' => { pages => { ':pageId' => 'page' } } }, ['GET'] )
127                  ->addRoute( books => { ':bookId' => { '*' => 'book' } }, ['GET'] );
128
129           Note that book() will be called for any path_info containing
130           /books/<$bookid>/<$other> except if $other == 'pages'.
131
132       to manage /properties/p1, /properties/p2 with p1() and p2(), use:
133             $self->addRoute( properties => [ 'p1', 'p2' ] );
134
135       defaultRoute($path)
136
137       This method defined which path_info to use if path_info is '/' or
138       empty.
139
140   Accessors
141       See Lemonldap::NG::Common::PSGI for inherited accessors (error,
142       languages, logLevel, staticPrefix, templateDir, links, syslog).
143

AUTHORS

150       LemonLDAP::NG team <http://lemonldap-ng.org/team>
151

BUG REPORT

153       Use OW2 system to report bug or ask for features:
154       <https://gitlab.ow2.org/lemonldap-ng/lemonldap-ng/issues>
155

DOWNLOAD

157       Lemonldap::NG is available at <https://lemonldap-ng.org/download>
158

COPYRIGHT AND LICENSE

160       See COPYING file for details.
161
162       This library is free software; you can redistribute it and/or modify it
163       under the terms of the GNU General Public License as published by the
164       Free Software Foundation; either version 2, or (at your option) any
165       later version.
166
167       This program is distributed in the hope that it will be useful, but
168       WITHOUT ANY WARRANTY; without even the implied warranty of
169       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
170       General Public License for more details.
171
172       You should have received a copy of the GNU General Public License along
173       with this program.  If not, see <http://www.gnu.org/licenses/>.
174
175
176
177perl v5.38.0                      2023-11L-e1m4onldap::NG::Common::PSGI::Router(3)