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:\u00e1en 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ónJsonExceptionsi 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:
<?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¿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.