Net::API::REST - Framework for RESTful APIs


    package MyPackage;
        use strict;
        use curry;
        use parent qw( Net::API::REST );
        use Net::API::Stripe;
    sub init
        my $self = shift( @_ );
        $self->{routes} =
        ## API version 1
        1 =>
            'favicon.ico' => $self->curry::noop,
            auth =>
                google =>
                    _handler => $self->curry::oauth_google,
                    callback => $self->curry::oauth_google(callback => 1),
                linkedin =>
                    _handler => $self->curry::oauth_linkedin,
                    callback => $self->curry::oauth_linkedin(callback => 1),
            stripe => $self->curry::stripe,
        $self->{api_version} = 1;
        $self->{supported_api_versions} = [qw( 1 )];
        ## By default, we support the GET and POST to access our endpoints
        ## It may be adjusted endpoint by endpoint and if nothing is specified this default is used.
        $self->{default_methods} = [qw( GET POST )];
        ## This is ALL possible supported methods
        $self->{supported_methods} = [qw( DELETE GET HEAD OPTIONS POST PUT )];
        $self->{supported_languages} = [qw( en-GB en fr-FR fr ja-JP )];
        $self->{key} = 'kAncmaDajnacSnbGmbXamn';
        ## We want JWE (Json Web Token encrypted). This will affect jwt_encode's behaviour
        $self->{jwt_encrypt} = 1;
        ## Because we are encrypting
        $self->{jwt_algo} = 'PBES2-HS256+A128KW';
        $self->{jwt_encoding} = 'A128GCM' unless( length( $self->{jwt_encoding} ) );
        $self->{jwt_accepted_algo} = [qw( PBES2-HS256+A128KW HS256 )];
        $self->{jwt_accepted_encoding} = [qw( A128GCM )];
        $self->SUPER::init( @_ );
        return( $self );
    sub stripe
        my $self = shift( @_ );
        my $ep = $self->endpoint;
        my $pinfo = $ep->path_info;
        my $remote_ip = $self->request->remote_ip;
        my $sig = $self->request->headers( 'Stripe-Signature' );
        return( $self->reply({ code => Apache2::Const::HTTP_BAD_REQUEST, message => "No signature found" }) ) if( !CORE::length( $sig ) );
        my $payload = $self->request->data || return( $self->reply({ code => Apache2::Const::HTTP_BAD_REQUEST, message => "No payload data received from the client." }) );
        ## Net::API::Stripe object
        my $stripe = Net::API::Stripe->new(
            # Enable debug to get debug data in http server log
            debug => 0,
            conf_file => "/home/john_doe/stripe-settings.json",
        ) || do
            $self->message( 3, "Unable to initiate a Net::API::Stripe object using the configuration file /home/john_doe/stripe-settings.json" );
            return( $self->reply({ code => Apache2::Const::HTTP_INTERNAL_SERVER_ERROR, message => $self->oops }) );
        ## Do an IP source check to be sure this is Stripe talking to us
        if( !defined( my $ip_check = $stripe->webhook_validate_caller_ip({ ip => $remote_ip, ignore_ip => $ignore_ip }) ) )
            return( $self->reply({ code => $stripe->error->code, message => $stripe->error->message }) );
        ## Now, we make sure this is Stripe sending this by checking the signature of the payload
        my $check = $stripe->webhook_validate_signature({
            secret => $signing_secret,
            signature => $sig,
            payload => $payload,
            time_tolerance => $max_time_spread,
        if( !defined( $check ) )
            return( $self->reply({code => $stripe->error->code, message => $stripe->error->message }) );
        ## Ok, if we are here, we passed al checks
        ## Don't wait, reply ok back to Stripe so our request does not time out
        $self->response->code( Apache2::Const::HTTP_OK );
        my $json = $self->json->utf8->encode({ code => 200, success => $self->true });
        $self->response->print( $json );
        # Do something with the payload received
        my $evt = $stripe->event( $payload ) || 
        return( $self->reply({ code => Apache2::Const::HTTP_INTERNAL_SERVER_ERROR, message => $self->oops }) );
        printf( STDERR "Received an event from api version %s on %s for Stripe object type %s\n", $evt->api_version, $evt->created->iso8601, $evt->type );
        return( Apache2::Const::HTTP_OK );




The purpose of this module is to provide a powerful, yet simple framework to implement a RESTful API under Apache2 mod_perl.


new( hash )

This initiates the package and take the following parameters:


This is a required parameter to be sent with a value set to a Apache2::RequestRec object


Optional. If set with a positive integer, this will activate verbose debugging message


Returns the Apache2::RequestRec object.


Returns the api URI as a URI object.

api_version( integer or decimal )

Get or sets the current api version on the server.

bailout( error string )

Given an error message, this will prepare the http header and response accordingly.

It will call gettext to get the localised version of the error message, so this method is expected to be overriden by inheriting package.

If the outgoing content type set is application/json then this will return a properly formatted standard json error, such as:

    { "error": { "code": 401, "message": "Something went wrong" } }

Otherwise, it will send to the client the message as is.

base_path( path )

If in the Directory directive of the Apache Virtual Host, a Net_API_REST_Base was set, this method will be set with this value.

compression_threshold( integer )

The number of bytes threshold beyond which, the reply method will gzip compress the data returned to the client.

decode_base64( data )

Given some data, this will decode it using base64 algorithm. It uses APR::Base64::decode in the background, because MIME::Decoder may have some issue under mod_perl.

decode_json( data )

This decode from utf8 some data into a perl structure.

If an error occurs, it will return undef and set an exception that can be accessed with the error method.

decode_url( $string )

Given a url-encoded string, this returns the decoded string

This uses APR::Request XS method.

decode_utf8( data )

Decode some data from ut8 into perl internal utf8 representation.

If an error occurs, it will return undef and set an exception that can be accessed with the error method.

default_methods( [ qw( GET POST ... ) ] )

This sets or gets the default methods supported by an endpoint.

encode_base64( data )

Given some data, this will encode it using base64 algorithm. It uses APR::Base64::encode in the background, because MIME::Decoder may have some issue under mod_perl.

encode_json( hash reference )

Given a hash reference, this will encode it into a json data representation.

However, this will not utf8 encode it, because this is done upon printing the data and returning it to the client.

encode_url( $string )

Given a string, this returns its url-encoded version

This uses APR::Request XS method.

encode_utf8( data )

This encode in ut8 the data provided and return it.

If an error occurs, it will return undef and set an exception that can be accessed with the error method.

endpoint( [ Net::API::REST::Endpoint object ] )

This gets or sets an Net::API::REST::Endpoint object.


Generates an uuid string and return it.


Checks whether an Authorization http header was provided, and get the Bearer value.

If no header was found, it returns an empty string.

If an error occurs, it will return undef and set an exception that can be accessed with the error method.


Returns a reference to a list of handlers enabled for a given phase.

    $handlers_list = $res->get_handlers( $hook_name );

A list of handlers configured to run at the child_exit phase:

    @handlers = @{ $res->get_handlers( 'PerlChildExitHandler' ) || []};

gettext( 'string id' )

Get the localised version of the string passed as an argument.

This is supposed to be superseded by the package inheriting from Net::API::REST


This is the main method called by Apache to handle the response. To make this work, in the Apache configuration, you must set the handler to your package and have your package inherit from Net::API::REST. For example:

    PerlResponseHandler MyPackage

When called by Apache, handler will initiate a Net::API::REST::Request object and a Net::API::REST::Response

If the incoming request is an OPTIONS request such as a typical one issued during a javascript Ajax call, it will call the method http_options() which will also set the cors policy by calling http_cors()

Finally, it will try to find a route for the endpoint sought in the incoming query, and construct a Net::API::REST::Endpoint object with the context information of the endpoint, including information such as variables that could exist in the path. For example:


Here the llc property has an id 123 and the directors property has an id 42. Those two variables are stored in the net::API::REST::Endpoint object. This object can then be accessed with the method endpoint

Having found a route, handler calls the anonymous subroutine in charge of handling the endpoint.

If no route was found, handler returns a 400 Bad Request.

If the endpoint handler returns undef(), handler will return a 500 Server Error, otherwise it will pass the return value back to Apache. The return value should be an Apache2::Const return code.

header_datetime( DateTime object )

Given a DateTime object, this sets it to GMT time zone and set the proper formatter (Net::API::REST::DateTime) so that the stringification is compliant with http headers standard.


Checks http request context and set the proper CORS http headers.


If the request is an OPTIONS request, this method is called. It will do a pre-flight check and look forward to see if the user has access to the resource sought and sets the response http headers accordingly.

init_headers( code reference )

If this is set, then Net::API::REST::handler will call it.


Checks if perl option is enabled in the Virtual Host and returns a boolean value


Returns a JSON object.

jwt_accepted_algo( string )

Get or set the algorithm supported for the JWT tokens.

jwt_accepted_encoding( string )

Get or set the supported encoding for the JWT tokens.

jwt_algo( string )

The chosen algorithm to create JWT tokens

jwt_decode( token )

Given a JWT token, this will decode it and returns a hash reference


Provided with an hash reference of parameters, and this will prepare the token data and call "encode_jwt" in Net::API::REST::JWT

It accepts the following arguments and additional arguments recognised by Net::API::REST::JWT can also be provided and will be passed to "encode_jwt" in Net::API::REST::JWT directly.

It returns the encrypted token as a string or undef if an error occurred which can be retrieved using the "error" in Module::Generic method.


This will set the alg property in the token.


This will set the aud property in the token payload.


This will set the enc property in the token payload.


If true, this will encrypt the token. When provided this will affect the algo.

For example, when not encrypted, by default the algorithm used is HS256, but when encryption is activated, the algorithm becomes PBES2-HS256+A128KW


This will set the exp property in the token payload.


This will set the iat property in the token payload.


This will set the iss property in the token payload.


This will set the key property in the token payload.


The hash data to become the token payload. It can contains discretionary elements.


This will set the sub property in the token payload.


If provided, this will set the exp property to iat + ttl







lang( string )

Set or get the current language

lang_unix( string )

Given a language, this returns a language code formatted the unix way, ie en-GB would become en_GB

lang_web( string )

Given a language, this returns a language code formatted the web way, ie en_GB would become en-GB

log_error( string )

Given a string, this will log the data into the error log.

When log_error is accessed with the Apache2::RequestRec the error gets logged into the Virtual Host log, but when log_error gets accessed via the Apache2::ServerUtil object, the error get logged into the Apache main error log.

print( list )

print out the list of strings and returns the number of bytes sent.


reply( http code, message | hash reference )

Given an http code and a message, or just a hash reference, reply will find out if the code provided is an error and format the replied json appropriately like:

    { "error": { "code": 400, "message": "Some error" } }

It will json encode the returned data and print it out back to the client after setting the http returned code.


Returns the Net::API::REST::Request object. This object is set early during the instantiation in the handler method.


Returns the Net::API::REST::Response object. This object is set early during the instantiation in the handler method.

route( URI object )

Given an uri, this will find the route for the endpoint sought. If nothing found, it will return an empty string.

Otherwise, a Net::API::REST::Endpoint is returned.

routes( hash reference )

This sets the routes for all the endpoints proposed by the RESTful server


Returns a Apache2::Server object


Tries hard to find out the version number of the Apache server.


supported_api_versions( array reference )

Get or set the list of supported api versions

supported_languages( array reference )

Get or set the list of supported language codes, such as fr_FR, en_GB, ja_JP, zh_TW, etc

supported_methods( array reference )

Get or set the list of supported http methods.

warn( list )

Given a list of string, this sends a warning.


If the http request is for /.well-know, then we simply decline to process it.

This does not mean it won't get processed, but just that we pass and let Apache handle it directly.

_try( object type, method name, @_ )

Given an object type, a method name and optional parameters, this attempts to call it.

Apache2 methods are designed to die upon error, whereas our model is based on returning undef and setting an exception with Module::Generic::Exception, because we believe that only the main program should be in control of the flow and decide whether to interrupt abruptly the execution, not some sub routines.

Net::API::REST::Endpoint methods


This specifies the level of access: private or restricted


Returns the handler found to handle the endpoint


Returns a boolean on whether the given method is allowed.


Returns an array reference of the methods allowed for this endpoint.


Returns a string for this path info, if any.


Returns a hash reference of name => value pairs for the variables found in the endpoint sought by in the http request. For example:


In this case, llc has an id value of 12 and the director an id value of 23. They will be recorded as variables as instructed by the route map set by the package using Net::API::REST


Jacques Deguest <>

CPAN ID: jdeguest


Apache2::Request, Apache2::RequestRec, Apache2::RequestUtil


Copyright (c) 2018-2019 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.