Crear una API REST con PHP: JSON, PDO y autenticación

Una API permite que diferentes aplicaciones se comuniquen mediante un contrato

Imagina que tienes un sistema de productos.

La información está almacenada en MySQL, pero quieres mostrarla dentro de:

Esos clientes no necesitan conectarse directamente a la base de datos.

Pueden comunicarse con una API PHP.

La API se convierte en una frontera

Decide qué información puede consultarse, qué operaciones están permitidas y bajo qué condiciones.

PHP puede identificar el método de la solicitud

<?php

$metodo = $_SERVER['REQUEST_METHOD'];

switch ($metodo) {

    case 'GET':
        // Consultar.
        break;

    case 'POST':
        // Crear.
        break;

    case 'PATCH':
        // Modificar.
        break;

    case 'DELETE':
        // Eliminar.
        break;

    default:
        http_response_code(405);
}

En una aplicación mayor, esta lógica normalmente termina dentro de un router o framework.

Pero comprenderla manualmente primero ayuda a entender qué está automatizando la herramienta.

Una solicitud POST o PATCH puede enviar información en formato JSON

El cuerpo de una solicitud podría contener:

{
    "nombre": "Monitor",
    "precio": 129990
}

PHP puede leer el body mediante php://input.

<?php

$contenido = file_get_contents(
    'php://input'
);

$datos = json_decode(
    $contenido,
    true
);

if (!is_array($datos)) {

    http_response_code(400);

    echo json_encode([
        'error' => 'JSON inválido'
    ]);

    exit;
}

Decodificar JSON no significa que los datos sean válidos

Todavía necesitas comprobar campos, tipos, reglas y permisos.

Consultar un recurso por identificador

<?php

$sql = "
    SELECT
        id,
        nombre,
        precio
    FROM productos
    WHERE id = :id
    LIMIT 1
";

$stmt = $pdo->prepare($sql);

$stmt->execute([
    'id' => $id
]);

$producto = $stmt->fetch(
    PDO::FETCH_ASSOC
);

if (!$producto) {

    http_response_code(404);

    echo json_encode([
        'error' => 'Producto no encontrado'
    ]);

    exit;
}

echo json_encode([
    'data' => $producto
]);

Aquí 404 comunica información importante

El cliente no recibe solamente un texto: también recibe un código HTTP que describe el resultado.

Eliminar un recurso también necesita autorización

<?php

$sql = "
    DELETE FROM productos
    WHERE id = :id
";

$stmt = $pdo->prepare($sql);

$stmt->execute([
    'id' => $id
]);

if ($stmt->rowCount() === 0) {

    http_response_code(404);

    echo json_encode([
        'error' => 'Producto no encontrado'
    ]);

    exit;
}

http_response_code(204);

204 No Content puede utilizarse cuando la operación fue correcta y no necesitas devolver un body.

Una API debe diferenciar entre datos técnicamente válidos y datos válidos para el negocio

Tipo

¿El precio realmente es numérico?

Rango

¿Puede ser negativo?

Longitud

¿Un nombre puede contener miles de caracteres?

Unicidad

¿Puede repetirse un email o código?

Regla de negocio

¿Puede cancelarse un pedido que ya fue despachado?

Separar controlador, servicio y acceso a datos evita una API formada por archivos gigantes

Un endpoint no debería convertirse en una mezcla de:

Podemos empezar separando responsabilidades.

Request
   ↓
Router
   ↓
Controller
   ↓
Service
   ↓
Repository
   ↓
PDO / MySQL

Controller

Recibe información relacionada con HTTP y construye la respuesta.

Service

Ejecuta reglas del negocio.

Repository

Encapsula operaciones relacionadas con persistencia.

Composer permite organizar las clases de la API mediante autoloading

Podemos utilizar PSR-4 para relacionar namespaces con el directorio src/.

{
    "autoload": {
        "psr-4": {
            "Ciborg\\Api\\": "src/"
        }
    }
}

Y organizar:

api/
│
├── composer.json
├── composer.lock
├── public/
│   └── index.php
│
├── src/
│   ├── Controllers/
│   ├── Services/
│   ├── Repositories/
│   ├── Http/
│   └── Database/
│
└── vendor/

Estar autenticado no significa poder hacer cualquier cosa

Supongamos que un usuario puede consultar sus pedidos.

No debería poder cambiar el identificador de la URL y consultar los pedidos de otra persona.

Debes comprobar propiedad o permisos

La lógica debería responder preguntas como:

Una API debe devolver errores consistentes sin revelar detalles internos

El cliente necesita comprender qué ocurrió.

Pero no necesita recibir:

Respuesta pública

{
    "error": "internal_error",
    "message": "No fue posible completar la operación."
}

El detalle técnico puede registrarse internamente para debugging.

Query parameters pueden permitir búsquedas y filtros

GET /productos?categoria=tecnologia
GET /productos?activo=1
GET /productos?buscar=teclado

Una API pública debería considerar límites de uso

Un cliente puede realizar miles de solicitudes por accidente o de manera abusiva.

Rate limiting

Permite restringir cuántas solicitudes puede realizar una identidad o cliente dentro de un período.

Límites por plan

En un SaaS, también puedes asociar consumo con planes o créditos.

Este tipo de control pertenece a la arquitectura del servicio, no solamente al routing.

Si trabajas con WordPress, ya existe una REST API que puedes extender

No siempre necesitas construir una API PHP desde cero.

WordPress proporciona su propia REST API y permite registrar endpoints personalizados.

Los mismos conceptos siguen siendo importantes: HTTP, JSON, autenticación, permisos, validación y códigos de estado.

Qué evitar al crear una API REST con PHP

Continúa profundizando en PHP