9. Endpoint POST: Creación de Recursos, Validación de Campos y Código 201 Created
Recibe datos JSON, valida tipos de datos y campos obligatorios, inserta registros con transacciones y devuelve la cabecera 201 Created con el ID generado.
Creación de Recursos con POST
El método POST se utiliza para crear nuevos recursos en el servidor. A diferencia de las lecturas, aquí entran en juego tres responsabilidades críticas:
- Validación estricta de entrada: Si los datos no cumplen las reglas de negocio, se debe responder con
HTTP 422 Unprocessable Entitydetallando los campos erróneos. - Persistencia segura: Inserción mediante consultas preparadas en PDO.
- Respuesta semántica: Devolver el código
HTTP 201 Createdcon los datos del recurso recién creado y su nuevo ID autoincremental.
Estructura de Errores 422 Estandarizada
Cuando falla la validación, el frontend espera saber exactamente qué campo falló para iluminarlo en rojo en el formulario:
{
"status": "error",
"code": 422,
"message": "Fallo en la validación de los datos",
"errors": {
"nombre": "El nombre es obligatorio y debe tener al menos 3 caracteres",
"precio": "El precio debe ser un número positivo mayor a 0"
}
}
⚡ Controlador de Creación (POST) con Validación y Código 201
Implementación completa en PHP nativo para procesar POST /api/productos:
<?php
declare(strict_types=1);
final class ProductoControladorPOST
{
/**
* POST /api/productos
*/
public function crear(): void
{
$payload = json_decode(file_get_contents('php://input'), true) ?? [];
// 1. Validar reglas de negocio
$errores = [];
$nombre = trim((string)($payload['nombre'] ?? ''));
if (mb_strlen($nombre) < 3) {
$errores['nombre'] = 'El nombre es obligatorio y debe tener al menos 3 caracteres.';
}
$precio = filter_var($payload['precio'] ?? null, FILTER_VALIDATE_FLOAT);
if ($precio === false || $precio <= 0) {
$errores['precio'] = 'El precio debe ser un número decimal mayor a cero.';
}
$stock = filter_var($payload['stock'] ?? 0, FILTER_VALIDATE_INT);
if ($stock === false || $stock < 0) {
$errores['stock'] = 'El stock debe ser un número entero mayor o igual a cero.';
}
// Si hay errores de validación, abortar con 422
if (!empty($errores)) {
ApiResponse::error('Datos inválidos para la creación', 422, $errores);
}
// 2. Insertar en base de datos con PDO
$db = Database::getConnection();
$stmt = $db->prepare('INSERT INTO productos (nombre, precio, stock, creado_en) VALUES (:nombre, :precio, :stock, NOW())');
$stmt->execute([
'nombre' => $nombre,
'precio' => $precio,
'stock' => $stock,
]);
$nuevoId = (int)$db->lastInsertId();
// 3. Responder con HTTP 201 Created
ApiResponse::success([
'id' => $nuevoId,
'nombre' => $nombre,
'precio' => $precio,
'stock' => $stock,
], 'Producto creado satisfactoriamente', 201);
}
}
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección¿Cuál es el código de estado HTTP estándar que debe devolver una API REST tras crear con éxito un nuevo recurso?
¿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.