/ 
Terse-0.109
River stage one • 9 direct dependents • 9 total dependents
/ Terse

NAME

Terse - Lightweight JSON APIs.

VERSION

Version 0.109

SYNOPSIS

package MyAPI;

use base 'Terse';

sub auth {
	my ($self, $t, $session) = @_;
	return 0 if $t->params->not;
	return $session;
}

sub hello_world {
	my ($self, $t) = @_;

	if ($t->params->throw_error) {
		$t->logError('throw 500 error which is also logged', 500);
		return;
	}

	$t->response->hello = "world";
}

sub delayed_hello_world {
	my ($self, $t) = @_;
	$t->delayed_response(sub {
		if ($t->params->throw_error) {
			$t->logError('throw 500 error which is also logged', 500);
			return;
		}

		... do something which takes a long time ...

		$t->response->hello = "world";
		return $t->response;
	});
}

.... MyAPI.psgi ...

use Terse;
use MyAPI;
our $api = MyAPI->new();

sub {
	my ($env) = (shift);
	Terse->run(
		plack_env => $env,
		application => $api,
		logger => Terse->new(
			info => sub { 
				say "info log line: " . $_[1]->{message};
			}, 
			err => sub { 
				say "err log line: " . $_[1]->{message}; 
			} 
		)
	);
};

....

plackup MyAPI.psgi

GET http://localhost:5000/?req=delayed_hello_world
# {"authenticated":1,"error":false,"errors":[],"hello":"world","status_code":200}
GET http://localhost:5000/?req=hello_world&not=1 
# {"authenticated":0,"error":true,"errors":["Invalid request"],"status_code":400}
GET http://localhost:5000/?req=hello_world&throw_error=1 
# {"authenticated":1,"error":true,"errors":["throw 500 error which is also logged"],"status_code":500}

Description

Alot of the inspiration, and some code, for this module came from JSONP - which is a module to quickly build JSON/JSONP web services, providing also some syntactic sugar acting a bit like a sort of DSL (domain specific language) for JSON. ( thanks Anselmo Canfora ACANFORA! )

There are several key differences between Terse and JSONP, the main being Terse uses Plack and not CGI. Terse also makes it simpler to provision the data which should be returned from the API (and what should not), finally it adds logging support.

Methods

new

Instantiate a new Terse object.

my $object = Terse->new(%params);

run

Run terse as a plack application.

Terse->run(
	login => 'login',
	logout => 'logout',
	auth => 'auth',
	insecure_session => 0,
	application => Terse->new(
		auth => sub { ... },
		login => sub { ... },
		logout => sub { ... }
	),
	plack_env => $env
);

The "application" does not need to be a "Terse application", the only requirment is it implements the auth, login and logout methods (go crazy!).

params

Retrieve params for the request.

$terse->params;

request

Returns the Plack::Request.

$terse->request;

session

Retrieve current session data, set in your auth or login methods

$terse->session;

response

Set the response body data.

$terse->response->foo = { ... };

logger

Set or Retrieve the logger for the application.

$terse->logger($logger);
$terse->logger->info();
$terse->logger->err();

logError

Log and raise an error message.

$terse->logError('this is an error message', 404);

logInfo

Log an info message.

$terse->logInfo('this an info message');

raiseError

Raise an error message.

$terse->raiseError('this is an error message', 404);

graft

Decode a JSON string.

$terse->response->graft('config', "{...}");

pretty

Set JSON to pretty print mode.

$terse->pretty(1);

serialize

Encode a perl struct as a JSON string.

$terse->serialize({ ... });

delayed_response

Delay the response for non-blocking I/O based server streaming or long-poll Comet push technology.

$terse->delayed_response(sub {
	$terse->response->test = 'okay';
	return $terse->response;
});

AUTHOR

LNATION, <email at lnation.org>

BUGS

Please report any bugs or feature requests to bug-terse at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Terse. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Terse

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2022 by LNATION.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)