8. Endpoints GET: Lectura de Colecciones, Paginación y Filtros por Parámetro
Implementa consultas de listado completo y detalle individual por ID (/api/productos y /api/productos/10) con soporte para paginación (limit/offset).
Diseño de Endpoints de Lectura (GET)
En una API RESTful bien estructurada, las consultas de lectura siguen dos patrones canónicos:
GET /api/productos: Retorna la colección de recursos (con filtros y paginación).GET /api/productos/{id}: Retorna el detalle individual de un único recurso. Si no existe, devuelve404 Not Found.
Paginación Segura con LIMIT y OFFSET
Nunca permitas que un endpoint devuelva todos los registros de una tabla sin límite (SELECT * FROM productos). Si la tabla crece a 100.000 filas, la memoria del servidor colapsará y el cliente se bloqueará.
La paginación estándar se controla mediante parámetros de consulta (Query Parameters):
pagina(opage): Página actual (por defecto 1).limite(olimit): Cantidad de elementos por página (por defecto 15, con un máximo de 100).- Fórmula del desplazamiento:
$offset = ($pagina - 1) * $limite;
⚡ Controlador de Lectura con Colección Paginada y Detalle Individual
Implementación en PHP puro para manejar GET /productos y GET /productos/{id}:
<?php
declare(strict_types=1);
final class ProductoControlador
{
/**
* GET /api/productos?pagina=1&limite=10
*/
public function listar(): void
{
$db = Database::getConnection();
// 1. Sanitizar parámetros de paginación
$pagina = max(1, (int)($_GET['pagina'] ?? 1));
$limite = min(100, max(1, (int)($_GET['limite'] ?? 10)));
$offset = ($pagina - 1) * $limite;
// 2. Obtener el conteo total de registros
$total = (int)$db->query('SELECT COUNT(*) FROM productos')->fetchColumn();
// 3. Obtener los registros paginados con consulta preparada
$stmt = $db->prepare('SELECT id, nombre, precio, stock, creado_en FROM productos ORDER BY id DESC LIMIT :limit OFFSET :offset');
$stmt->bindValue(':limit', $limite, PDO::PARAM_INT);
$stmt->bindValue(':offset', $offset, PDO::PARAM_INT);
$stmt->execute();
$productos = $stmt->fetchAll();
// 4. Emitir respuesta con metadatos de paginación
ApiResponse::success([
'items' => $productos,
'paginacion' => [
'total' => $total,
'pagina_actual'=> $pagina,
'por_pagina' => $limite,
'total_paginas'=> (int)ceil($total / $limite),
]
], 'Colección de productos obtenida');
}
/**
* GET /api/productos/{id}
*/
public function ver(int $id): void
{
$db = Database::getConnection();
$stmt = $db->prepare('SELECT * FROM productos WHERE id = :id');
$stmt->execute(['id' => $id]);
$producto = $stmt->fetch();
if (!$producto) {
ApiResponse::error("Producto con ID $id no encontrado", 404);
}
ApiResponse::success($producto, 'Detalle de producto obtenido');
}
}
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección¿Por qué se debe vincular el parámetro :limit en PDO usando bindValue con PDO::PARAM_INT en lugar de inyectarlo directo en el execute([":limit" => $limite])?
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.🚀 ¿Quieres dominar APIs RESTful con PHP Puro, JSON & JWT y crear proyectos reales?
Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.