Tema 9 · Endpoint POST

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:

  1. Validación estricta de entrada: Si los datos no cumplen las reglas de negocio, se debe responder con HTTP 422 Unprocessable Entity detallando los campos erróneos.
  2. Persistencia segura: Inserción mediante consultas preparadas en PDO.
  3. Respuesta semántica: Devolver el código HTTP 201 Created con 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:

ProductoControladorPOST.php
Solo lectura
<?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
1 Pregunta
Pregunta 1
¿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.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.