/ 
PAGI-0.001008
/ PAGI::Endpoint::HTTP

NAME

PAGI::Endpoint::HTTP - Class-based HTTP endpoint handler

SYNOPSIS

package MyApp::UserAPI;
use parent 'PAGI::Endpoint::HTTP';
use Future::AsyncAwait;

async sub get {
    my ($self, $req, $res) = @_;
    my $users = get_all_users();
    await $res->json($users);
}

async sub post {
    my ($self, $req, $res) = @_;
    my $data = await $req->json;
    my $user = create_user($data);
    await $res->status(201)->json($user);
}

async sub delete {
    my ($self, $req, $res) = @_;
    my $id = $req->path_param('id');
    delete_user($id);
    await $res->status(204)->empty;
}

# Use with PAGI server
my $app = MyApp::UserAPI->to_app;

DESCRIPTION

PAGI::Endpoint::HTTP provides a Starlette-inspired class-based approach to handling HTTP requests. Define methods named after HTTP verbs (get, post, put, patch, delete, head, options) and the endpoint automatically dispatches to them.

Features

  • Automatic method dispatch based on HTTP verb

  • 405 Method Not Allowed for undefined methods

  • OPTIONS handling with Allow header

  • HEAD falls back to GET if not defined

  • Factory methods for framework customization

HTTP METHODS

Define any of these async methods to handle requests:

async sub get { my ($self, $req, $res) = @_; ... }
async sub post { my ($self, $req, $res) = @_; ... }
async sub put { my ($self, $req, $res) = @_; ... }
async sub patch { my ($self, $req, $res) = @_; ... }
async sub delete { my ($self, $req, $res) = @_; ... }
async sub head { my ($self, $req, $res) = @_; ... }
async sub options { my ($self, $req, $res) = @_; ... }

Each receives:

$self - The endpoint instance
$req - A PAGI::Request object (or custom request class)
$res - A PAGI::Response object (or custom response class)

CLASS METHODS

to_app

my $app = MyEndpoint->to_app;

Returns a PAGI-compatible async coderef that can be used directly with PAGI::Server or composed with middleware.

request_class

sub request_class { 'PAGI::Request' }

Override to use a custom request class.

response_class

sub response_class { 'PAGI::Response' }

Override to use a custom response class.

INSTANCE METHODS

dispatch

await $endpoint->dispatch($req, $res);

Dispatches the request to the appropriate HTTP method handler. Called automatically by to_app.

allowed_methods

my @methods = $endpoint->allowed_methods;

Returns list of HTTP methods this endpoint handles.

FRAMEWORK INTEGRATION

Framework designers can subclass and customize:

package MyFramework::Endpoint;
use parent 'PAGI::Endpoint::HTTP';

sub request_class { 'MyFramework::Request' }
sub response_class { 'MyFramework::Response' }

# Add framework-specific helpers
sub db {
    my ($self) = @_;
    $self->{db} //= connect_db();
}

SEE ALSO

PAGI::Endpoint::WebSocket, PAGI::Endpoint::SSE, PAGI::Request, PAGI::Response