Tema 5 · Respuestas JSON

5. Emisión de Respuestas JSON Estandarizadas y http_response_code

Configura la cabecera Content-Type: application/json, utiliza json_encode con banderas de seguridad y estandariza la estructura de tus respuestas.

Estandarización de la Envoltura JSON (Response Envelope)

Para que los desarrolladores de frontend y aplicaciones móviles consuman tu API con facilidad, todas las respuestas (tanto las exitosas como las fallidas) deben seguir una **estructura envelope consistente y predecible**.

El estándar de la industria recomienda incluir al menos:

  • status: Estado cualitativo ("success", "fail" o "error").
  • data: Objeto o array con la información solicitada en caso de éxito.
  • message: Mensaje descriptivo legible para humanos.
  • errors: Array detallado con fallas de validación campo por campo si ocurrió un error 422.

Banderas Críticas de json_encode en PHP

En producción, nunca llames a json_encode($datos) sin banderas de protección y codificación adecuada:

  • JSON_UNESCAPED_UNICODE: Evita que tildes, caracteres en español o emojis se conviertan en caracteres escapados feos (ej: \u00e1 en lugar de á).
  • JSON_UNESCAPED_SLASHES: Evita que las barras inclinadas en URLs se escapen con barras invertidas (https:\/\/ejemplo.com).
  • JSON_THROW_ON_ERROR: Lanza una excepción JsonException si ocurre un error de serialización (como referencias circulares o datos binarios corruptos).

⚡ Clase ApiResponse para Centralizar Salidas en PHP Nativo

Una clase orientada a objetos sencilla para estandarizar respuestas exitosas, paginadas o de error:

ApiResponse.php
Solo lectura
<?php
declare(strict_types=1);

final class ApiResponse
{
    /**
     * Emite una respuesta exitosa (200 OK o 201 Created).
     */
    public static function success(mixed $data = null, string $message = 'Operación exitosa', int $code = 200): void
    {
        self::enviar($code, [
            'status'  => 'success',
            'code'    => $code,
            'message' => $message,
            'data'    => $data,
        ]);
    }

    /**
     * Emite una respuesta de error del cliente o del servidor.
     */
    public static function error(string $message, int $code = 400, ?array $errors = null): void
    {
        $payload = [
            'status'  => 'error',
            'code'    => $code,
            'message' => $message,
        ];

        if ($errors !== null) {
            $payload['errors'] = $errors;
        }

        self::enviar($code, $payload);
    }

    private static function enviar(int $code, array $payload): void
    {
        http_response_code($code);
        header('Content-Type: application/json; charset=utf-8');
        header('X-Content-Type-Options: nosniff');

        echo json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
        exit;
    }
}

// Ejemplos de uso:
// ApiResponse::success(['id' => 10, 'nombre' => 'Laptop'], 'Producto creado', 201);
// ApiResponse::error('Credenciales incorrectas', 401);
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Qué bandera de json_encode evita que las tildes y caracteres en español se conviertan en secuencias como \u00f3?
🦉
¿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.