Aprende a diseñar, implementar y consumir APIs REST con PHP siguiendo los principios y buenas prácticas de la arquitectura más utilizada en servicios web modernos.
REST (Representational State Transfer) es un estilo de arquitectura para diseñar servicios web. Fue presentado por Roy Fielding en su tesis doctoral en 2000 y se ha convertido en el estándar de facto para el diseño de APIs web modernas.
REST es un conjunto de principios arquitectónicos, no un protocolo o estándar. Las API que siguen estos principios se denominan "RESTful".
Imagen: Comunicación cliente-servidor a través de una API REST utilizando recursos, verbos HTTP y representaciones.
Los recursos se identifican mediante URIs y se manipulan mediante representaciones. Simplifica la arquitectura general y mejora la visibilidad de las interacciones.
Cada petición contiene toda la información necesaria y no depende de peticiones anteriores. El servidor no almacena contexto entre peticiones.
La arquitectura está compuesta por múltiples capas jerárquicas que pueden evolucionar de forma independiente, permitiendo escalabilidad y flexibilidad.
En una API REST, todo es un recurso. Un recurso puede ser un objeto, un servicio, o cualquier entidad que pueda ser identificada, nombrada y manipulada a través de la web. Cada recurso es accesible a través de una URL única.
Recurso | URL | Descripción | Ejemplo |
---|---|---|---|
Colección | /recursos |
Representa todos los recursos de un tipo | /usuarios |
Elemento | /recursos/{id} |
Representa un recurso específico por su ID | /usuarios/123 |
Subrecurso | /recursos/{id}/subrecursos |
Todos los subrecursos de un recurso específico | /usuarios/123/pedidos |
Filtrado | /recursos?param=valor |
Recursos filtrados por parámetros de consulta | /usuarios?activo=true |
Los métodos HTTP definen las acciones que se pueden realizar sobre los recursos. Estos se corresponden con las operaciones CRUD (Create, Read, Update, Delete) de las bases de datos.
Crea un nuevo recurso en el servidor.
POST /usuarios
Recupera un recurso o una colección.
GET /usuarios/123
Actualiza un recurso existente.
PUT /usuarios/123
Elimina un recurso existente.
DELETE /usuarios/123
Headers:
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJ9...
URL Parameters:
id: 1
Headers:
Content-Type: application/json
Cache-Control: max-age=3600
Body:
{
"id": 1,
"nombre": "Smartphone XYZ",
"precio": 599.99,
"categoria": "Electrónica",
"disponible": true,
"creado": "2025-01-15T10:30:00Z"
}
JSON (JavaScript Object Notation) es el formato estándar para intercambiar datos en APIs REST. Es ligero, fácil de leer para humanos y fácil de procesar para las máquinas.
{
"id": 1,
"nombre": "Juan Pérez",
"correo": "juan@example.com",
"activo": true,
"rol": "admin",
"creado": "2025-01-15T10:30:00Z"
}
{
"usuarios": [
{
"id": 1,
"nombre": "Juan Pérez",
"correo": "juan@example.com"
},
{
"id": 2,
"nombre": "María López",
"correo": "maria@example.com"
}
],
"total": 2,
"pagina": 1,
"porPagina": 10
}
Los códigos de estado HTTP comunican el resultado de una petición. Usar los códigos correctos mejora la usabilidad de tu API, permite un mejor manejo de errores y facilita la depuración.
Seguir estas recomendaciones te ayudará a crear APIs más intuitivas, mantenibles y fáciles de usar.
/usuarios
en lugar de /getUsuarios
/api/v1/usuarios
Comunica claramente el resultado
Para colecciones grandes
Mediante parámetros de consulta
Usa herramientas como Swagger/OpenAPI
Tanto en cliente como en servidor
Usa HTTPS y autenticación apropiada
Aplicación o navegador
GET POST PUT DELETE
Base de datos, archivos, etc.
file_get_contents()
para peticiones sencillasLas APIs REST siguen principios de diseño que las hacen escalables, mantenibles y fáciles de usar. Utilizan URLs para identificar recursos, métodos HTTP para manipularlos, y códigos de estado para comunicar resultados. En las próximas lecciones, veremos cómo implementar y consumir APIs REST con PHP.
<?php
// Consumir una API REST con file_get_contents
$url = 'https://fakestoreapi.com/products/1';
// Configurar el contexto para la solicitud
$options = [
'http' => [
'method' => 'GET',
'header' => 'Accept: application/json'
]
];
$context = stream_context_create($options);
// Realizar la petición
$response = file_get_contents($url, false, $context);
// Verificar si hubo errores
if ($response === false) {
echo "Error al obtener datos de la API";
exit;
}
// Decodificar la respuesta JSON
$data = json_decode($response, true);
// Mostrar los datos
echo "<h3>{$data['title']}</h3>";
echo "<p>Precio: \${$data['price']}</p>";
echo "<p>Categoría: {$data['category']}</p>";
echo "<p>{$data['description']}</p>";
?>
<?php
// Consumir una API REST con cURL
$url = 'https://fakestoreapi.com/products?limit=5';
// Inicializar cURL
$ch = curl_init();
// Configurar opciones de cURL
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Accept: application/json',
'Content-Type: application/json'
]);
// Ejecutar la petición
$response = curl_exec($ch);
// Verificar si hubo errores
if(curl_errno($ch)) {
echo 'Error cURL: ' . curl_error($ch);
exit;
}
// Obtener código de estado HTTP
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo "Código de estado: $httpCode<br>";
// Cerrar sesión cURL
curl_close($ch);
// Decodificar la respuesta JSON
$productos = json_decode($response, true);
// Mostrar resultados
echo "<ul>";
foreach ($productos as $producto) {
echo "<li>{$producto['title']} - \${$producto['price']}</li>";
}
echo "</ul>";
?>
<?php
// Enviar datos JSON a una API con POST
$url = 'https://fakestoreapi.com/products';
// Datos a enviar en formato JSON
$data = [
'title' => 'Nuevo Producto',
'price' => 99.99,
'description' => 'Una descripción del nuevo producto',
'image' => 'https://example.com/image.jpg',
'category' => 'electronics'
];
// Convertir array a JSON
$jsonData = json_encode($data);
// Inicializar cURL
$ch = curl_init();
// Configurar opciones de cURL para POST
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($jsonData)
]);
// Ejecutar la petición
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
// Cerrar sesión cURL
curl_close($ch);
// Verificar respuesta
if ($httpCode == 201) { // 201 Created
$productoCreado = json_decode($response, true);
echo "Producto creado correctamente con ID: {$productoCreado['id']}<br>";
echo "<pre>";
print_r($productoCreado);
echo "</pre>";
} else {
echo "Error al crear el producto. Código: $httpCode<br>";
echo "Respuesta: $response";
}
?>