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

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

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

       See COPYING file for details.

       This  library  is  free  software;  you  can  redistribute it and/or modify it under the terms of the GNU
       General Public License as published by the Free Software  Foundation;  either  version  2,  or  (at  your
       option) any later version.

       This  program  is  distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
       the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General  Public
       License for more details.

       You  should  have received a copy of the GNU General Public License along with this program.  If not, see
       <http://www.gnu.org/licenses/>.

perl v5.40.1                                       2025-05-01              Lemonldap::NG:...n::PSGI::Router(3pm)

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

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

       See Lemonldap::NG::Common::PSGI for logging methods, content sending,...

   InitializationmethodsaddRoute($word,$dest,$methods)

       Declare a REST route. Arguments:

       $word:
           the first word of /path/info.

       $dest:
           string, sub ref or hash ref (see "Route types" below)

       $methods:
           array ref containing the methods concerned by this route.

       Route types

       As seen in "SYNOPSIS", you can declare routes with variable component. $dest can be:

       a word:
           the name of the method to call

       undef:
           $word is used as $dest

       a ref to code:
           an anonymous subroutin to call

       a hash ref:
           it's a recursive call to `{ $word => $dest }`

       an array ref:
           in  this  case  each  element  of the array will be considered as `{ $element => $element }`. So each
           element must be a word that makes a correspondence between a path_info word and a subroutine

       Some special $word:

       ':name':
           the word in path_info will be stored in GET parameters

       '*':
           the subroutine will be called with the word of path_info as second argument (after $req)

       'something.html':
           if  $word  finishes  with  '.html',  and  $dest  is  undef,  then  sendHtml()  will  be  called  with
           'something.tpl' as template name.

       Examples:

       to manage http://.../books/127 with book() where 127 is the book number, use:
             $self->addRoute( books => { ':bookId' => 'book' }, ['GET'] );

           bookId parameter will be stored in $req->params('bookId');

       to manage http://.../books/127/pages/5 with page(), use:
             $self->addRoute( books => { ':bookId' => { pages => { ':pageId' => 'page' } } }, ['GET'] );

       to manage simultaneously the 2 previous examples
             $self->addRoute( books => { ':bookId' => { pages => { ':pageId' => 'page' } } }, ['GET'] )
                  ->addRoute( books => { ':bookId' => { '*' => 'book' } }, ['GET'] );

           Note  that  book()  will  be  called for any path_info containing /books/<$bookid>/<$other> except if
           $other == 'pages'.

       to manage /properties/p1, /properties/p2 with p1() and p2(), use:
             $self->addRoute( properties => [ 'p1', 'p2' ] );

       defaultRoute($path)

       This method defined which path_info to use if path_info is '/' or empty.

   Accessors
       See Lemonldap::NG::Common::PSGI  for  inherited  accessors  (error,  languages,  logLevel,  staticPrefix,
       templateDir, links, syslog).

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

       <http://lemonldap-ng.org/>,      Lemonldap::NG::Portal,      Lemonldap::NG::Handler,     Plack,     PSGI,
       Lemonldap::NG::Common::PSGI, Lemonldap::NG::Common::PSGI::Request, HTML::Template,

         package My::PSGI;

         use base Lemonldap::NG::Common::PSGI::Router;

         sub init {
           my ($self,$args) = @_;
           # Will be called 1 time during startup

           # Declare REST routes (could be HTML templates or methods)
           $self->addRoute ( 'index.html', undef, ['GET'] )
                ->addRoute ( books => { ':book' => 'booksMethod' }, ['GET', 'POST'] )
                ->addRoute ( properties => { '*' => 'propertiesMethod' }, ['GET', 'POST', 'PUT', 'DELETE']);

           # Default route (ie: PATH_INFO == '/')
           $self->defaultRoute('index.html');

           # See Lemonldap::NG::Common::PSGI for other options

           # Return a boolean. If false, then error message has to be stored in
           # $self->error
           return 1;
         }

         sub booksMethod {
           my ( $self, $req, @otherPathInfo ) = @_;
           my $book = $req->params('book');
           my $method = $req->method;
           ...
           $self->sendJSONresponse(...);
         }

         sub propertiesMethod {
           my ( $self, $property, @otherPathInfo ) = @_;
           my $method = $req->method;
           ...
           $self->sendJSONresponse(...);
         }

       This package could then be called as a CGI, using FastCGI,...

         #!/usr/bin/env perl

         use My::PSGI;
         use Plack::Handler::FCGI; # or Plack::Handler::CGI

         Plack::Handler::FCGI->new->run( My::PSGI->run() );