Cómo crear una API REST con PHP desde cero: guía práctica y segura (2026)

Cómo crear una API REST con PHP desde cero es un proceso directo si estructuras bien las rutas, respondes siempre en JSON y usas una capa de datos segura. En esta guía vas a montar un endpoint funcional (CRUD básico), devolver códigos HTTP correctos y dejar preparada la API para crecer. Algunos pasos pueden variar según tu servidor (Apache/Nginx) y tu entorno local.

El objetivo es que, al final, puedas llamar endpoints tipo GET /api/users o POST /api/users y recibir respuestas consistentes en application/json.

La forma más rápida de crear una API REST en PHP (paso a paso)

1. Crea la carpeta del proyecto (por ejemplo api-php) y define un punto de entrada único: public/index.php.
2. Configura el “front controller”: todo request debe entrar por index.php para poder rutear por método y URL ($_SERVER['REQUEST_METHOD'] y $_SERVER['REQUEST_URI']).
3. Normaliza la salida: fija cabeceras como Content-Type: application/json; charset=utf-8 y evita imprimir HTML.
4. Lee el body JSON correctamente cuando sea necesario: file_get_contents('php://input') + json_decode(..., true), validando que el JSON sea válido.
5. Define rutas mínimas (ejemplo): GET /api/users, GET /api/users/{id}, POST /api/users, PUT /api/users/{id}, DELETE /api/users/{id}.
6. Conecta a la base de datos con PDO y activa modo de errores: PDO::ATTR_ERRMODE en PDO::ERRMODE_EXCEPTION.
7. Usa siempre consultas preparadas (prepared statements) para evitar inyecciones SQL; jamás concatenes entrada del usuario en SQL.
8. Devuelve códigos HTTP correctos: 201 al crear, 200 al listar/leer, 204 al borrar sin body, 400 si falta un campo, 404 si no existe, 500 en fallos inesperados.
9. Prueba con un cliente HTTP (Postman/curl) y valida que cada endpoint responda con JSON consistente (incluyendo errores).

Ver documentación oficial de PHP (PDO)

Estructura recomendada y ruteo simple sin frameworks

Para empezar sin frameworks, lo más estable es usar un front controller y un ruteo por método + path. Una estructura mínima típica:

• public/index.php (entrada única)
• src/Router.php (match de rutas)
• src/Db.php (conexión PDO)
• src/Controllers/UserController.php (lógica por recurso)

En el ruteo, evita “ifs” interminables. Un patrón práctico es mapear rutas a funciones usando clave METHOD + PATH, por ejemplo GET:/api/users o GET:/api/users/{id}. En PHP puro, puedes parsear la URL con parse_url() y separar segmentos del path.

En local, si quieres una prueba rápida sin configurar Apache, el servidor embebido de PHP puede servir el directorio public con un comando como php -S localhost:8000 -t public. En producción, lo habitual es usar Apache/Nginx con el DocumentRoot apuntando a public.

Entrada (request): JSON, validación y reglas claras

• Body JSON: decodifica con json_decode y si falla, responde 400 con un mensaje tipo {"error":"JSON inválido"}.
• Validación mínima: comprueba campos obligatorios y tipos. Si falta algo, responde 422 o 400 (elige uno y sé consistente en toda la API).
• ID en la URL: valida que {id} sea numérico (o UUID si así lo decides) antes de consultar la base.

Salida (response): formato consistente y códigos HTTP

• Siempre JSON: incluso en errores. Evita mezclar HTML/strings sueltos.
• Envelopes útiles: {"data": ...} para éxito y {"error": "...", "details": ...} para fallos.
• No filtres detalles sensibles: en errores 500, no devuelvas trazas ni SQL; registra en servidor y muestra un mensaje genérico.

Problemas comunes y soluciones rápidas

Siempre devuelve 404 aunque la URL existe

• Causa probable: el servidor no está enviando todas las rutas a public/index.php (falta reescritura o el DocumentRoot no apunta a public).
• Solución rápida: en Apache, habilita reescritura y configura reglas para que /api/... caiga en el front controller. En Nginx, revisa la directiva equivalente (try_files).
• Qué comprobar: que $_SERVER['REQUEST_URI'] muestre el path esperado y que el script que corre sea public/index.php.

El JSON llega vacío o null

• Causa probable: el cliente no envía JSON válido o falta la cabecera Content-Type: application/json.
• Solución rápida: en tu cliente HTTP, envía el body como JSON real y define el header correcto. En PHP, lee php://input y valida json_last_error().
• Qué comprobar: registra temporalmente el contenido raw de php://input (solo en desarrollo) para confirmar lo que llega.

Error de CORS al llamar desde el navegador

• Causa probable: el navegador bloquea la solicitud por políticas de origen cruzado (falta Access-Control-Allow-Origin o el preflight OPTIONS no está contemplado).
• Solución rápida: añade manejo de OPTIONS y permite solo orígenes necesarios (no uses * en producción si hay credenciales o tokens sensibles).
• Qué comprobar: en la consola del navegador, revisa si el fallo es en el preflight y qué header exacto se reclama.

SQL lento, errores al insertar o riesgo de inyección

• Causa probable: consultas sin índices, concatenación de variables en SQL, o manejo inconsistente de tipos.
• Solución rápida: migra a PDO con consultas preparadas, valida datos y crea índices en columnas consultadas por ID/clave.
• Qué comprobar: que nunca exista un SQL del tipo "... WHERE id=$id" y que todas las entradas pasen por parámetros.

Respuestas 500 sin pista de qué pasó

• Causa probable: errores PHP no visibles por configuración o excepciones no capturadas.
• Solución rápida: en desarrollo, activa reporting y captura excepciones globalmente para devolver un error JSON controlado. En producción, registra en logs y muestra un mensaje genérico.
• Qué comprobar: el log del servidor (Apache/Nginx/PHP-FPM) y que tu API devuelva un JSON de error consistente.

Preguntas frecuentes

¿Necesito un framework (Laravel, Slim, Symfony) para una API REST en PHP?

No es obligatorio. Para un MVP o un servicio pequeño, PHP puro con un ruteo simple funciona bien. Cuando crece el proyecto, un framework ayuda con routing robusto, middlewares, validación, testing y seguridad, pero añade complejidad.

¿Qué método es mejor: PDO o mysqli?

PDO suele ser la opción más flexible porque unifica acceso a distintos motores y facilita un manejo consistente de errores. Lo importante no es la librería, sino usar consultas preparadas y validar entradas siempre.

¿Cómo versiono la API sin romper clientes?

El enfoque más común es versionar por ruta, por ejemplo /api/v1/, y mantener compatibilidad mientras migras. También puedes versionar por header, pero en implementaciones simples la ruta suele ser más clara.

¿Qué autenticación conviene para una API REST?

Depende del caso: tokens tipo Bearer (por ejemplo JWT) son comunes para APIs stateless. Si hay sesiones y navegador, debes contemplar también CSRF y configuración cuidadosa de CORS. En cualquier caso, usa HTTPS en producción.

¿Cuáles son los códigos HTTP “mínimos” que debería implementar?

Como base: 200 (ok), 201 (creado), 204 (sin contenido), 400 (request inválido), 401 (no autenticado), 403 (sin permisos), 404 (no existe) y 500 (error interno). Mantén consistencia entre endpoints.

Si quieres escalar esta API, el siguiente paso es formalizar contratos (esquemas de request/response), agregar autenticación, rate limiting y pruebas automatizadas. Para profundizar y conectar conceptos, también puedes revisar qué enfoque te conviene y cómo se compara con otras arquitecturas desde estos recursos internos: API REST vs API SOAP: diferencias y cuándo usar cada una, diferencias entre API REST y API “de jabón” (SOAP), qué es un servidor web y cómo funciona y diferencias entre XAMPP y WAMP.