---
name: "Lemonldap::NG::Common::PSGI::Router"
section: "3pm"
platform: "linux"
package: "liblemonldap-ng-common-perl"
version: "2.21.2+ds-1+deb13u3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Lemonldap::NG::Common::PSGI::Router"
---

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

Base library for REST APIs of Lemonldap::NG.

## NAME

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

## SYNOPSIS

```
  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() );
```

## DESCRIPTION

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

## METHODS

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

### Initialization methods

*addRoute ( $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).

## SEE ALSO

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

## AUTHORS

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

  ## BUG REPORT

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

## DOWNLOAD

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

## COPYRIGHT AND LICENSE

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/\>.