BookinglyTech News
Software

Lanzan HTTP::API::Core, una capa independiente para clientes JSON API en Perl

El nuevo módulo permite separar la lógica de transporte de las políticas de cliente, simplificando retries, paginación y autenticación.

2 min de lecturaDev.to0 vistas

El desarrollador pannakoota publicó HTTP::API::Core, una biblioteca ligera que actúa como capa intermedia entre cualquier cliente HTTP de Perl y la lógica de negocio de un API JSON. La idea central es mantener el transporte (HTTP::Tiny, LWP, Mojo::UserAgent, Furl o un transport personalizado) desacoplado de las políticas de manejo de errores, reintentos, límites de velocidad, paginación y autenticación.

Separación de responsabilidades

Con HTTP::API::Core, el cliente define sólo la URL base, cabeceras comunes y opciones de timeout o retry. El módulo se encarga de aplicar políticas genéricas: reintentos con back‑off exponencial y jitter, interpretación de cabeceras Retry‑After y X‑RateLimit-*; normaliza la información de límites de velocidad y ofrece un iterador único para paginación, ya sea por cursor, número de página o URL siguiente. El código de ejemplo muestra cómo crear una instancia y realizar una petición GET:

use HTTP::API::Core;
my $api = HTTP::API::Core->new(
    base_url => 'https://api.example.com',
    headers  => { Authorization => "Bearer $ENV{API_TOKEN}" },
    timeout  => 10,
    retry    => { attempts => 3, base_delay => 0.25, max_delay => 5, jitter => 1 },
);
my $response = $api->get('/users');
my $data = $response->json;

El cliente de la API puede seguir siendo una función mínima que delega en $api->get y extrae el JSON, manteniendo el código específico del dominio muy compacto.

Reintentos y seguridad

Los reintentos se aplican por defecto solo a métodos idempotentes (GET, HEAD, PUT, DELETE, OPTIONS). No se vuelve a intentar automáticamente POST ni PATCH, a menos que el desarrollador indique explícitamente que el endpoint admite POST idempotente. Los fallos que disparan reintentos incluyen códigos 408, 425, 429 y cualquier 5xx, así como errores de transporte.

Paginación unificada

Para APIs que usan cursores:

my $pager = $api->paginate('/users', mode => 'cursor', items => 'data.users', next => 'meta.next_cursor', query => { limit => 100 });
while (my $user = $pager->next) { ... }

Para APIs basadas en número de página:

my $pager = $api->paginate('/users', mode => 'page', items => 'users', page_size => 100);
my @users = $pager->all;

El iterador detecta respuestas rotas y evita bucles infinitos.

Hooks de autenticación y observabilidad

HTTP::API::Core expone ganchos (before_request, after_response, on_error) que permiten inyectar cabeceras de autorización, registrar métricas o enviar trazas sin mezclar esas preocupaciones con la lógica del cliente. Incluye pequeños helpers para autenticación Bearer, Basic y API‑key; la gestión de tokens OAuth queda fuera del núcleo a propósito.

Disponibilidad

El proyecto está publicado en GitHub bajo una licencia permissiva y no pretende sustituir a los clientes HTTP existentes, sino complementarlos. El repositorio está disponible en Repositorio en GitHub.

En resumen, HTTP::API::Core ofrece una base reutilizable para cualquier cliente Perl que necesite manejar de forma consistente políticas comunes de API sin atarse a una implementación HTTP concreta, lo que reduce código duplicado y facilita pruebas y mantenimiento.

Historias Relacionadas