REST

Definición

REST (siglas de Representational State Transfer) es un estilo arquitectónico para diseñar APIs sobre el protocolo HTTP. Lo propuso Roy Fielding en su tesis doctoral en el año 2000 y desde mediados de los 2010 es el estándar de facto para APIs web públicas y privadas.

REST no es una tecnología ni un protocolo: es un conjunto de principios sobre cómo organizar una API. Si los sigues, tu API se llama RESTful. Si los sigues a medias (como casi todo el mundo), se llama "REST-ish" o, más honestamente, "JSON sobre HTTP".

La idea clave: tu sistema expone recursos (cosas: usuarios, productos, pedidos) identificados por URLs estables, y los clientes operan sobre ellos usando los verbos HTTP que ya existen (GET para leer, POST para crear, PUT/PATCH para modificar, DELETE para borrar). No reinventas vocabulario — usas el de la web.

Cómo funciona

REST se basa en seis principios. Los relevantes para el día a día:

1. Recursos como sustantivos: la URL identifica una cosa, no una acción.
   • ✓ Bien: /productos/12345
   • ✗ Mal: /getProductoById?id=12345
2. Verbos HTTP para acciones: el método de la petición indica qué hacer con el recurso.
3. Sin estado (stateless): cada petición lleva toda la info necesaria — el servidor no recuerda peticiones anteriores. Hace que la API escale fácil.
4. Respuestas con códigos HTTP estándar: 200 OK, 201 Created, 404 Not Found, 401 Unauthorized, 500 Internal Server Error...
5. Formato uniforme de intercambio (típicamente JSON, aunque REST en sí no lo impone).
6. Cacheable: las respuestas indican si son cacheables y por cuánto tiempo.

Verbos HTTP típicos en REST

"Idempotente" significa que hacer la operación N veces produce el mismo efecto que hacerla 1 vez. GET y DELETE son idempotentes; POST no (cada POST crea un recurso nuevo).

Ejemplo práctico

Crear un nuevo producto en el catálogo de IMDICA y luego consultarlo:

// 1. Crear el producto (POST)
const crear = await fetch('https://api.imdica.es/productos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ABC123',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    nombre: 'Fresa de carburo Ø10mm',
    referencia: 'FRC-010-CAR',
    precio: 23.50,
    stock: 47
  })
});

// El servidor responde 201 Created con el recurso creado
const producto = await crear.json();
console.log(producto.id); // → 12345

// 2. Consultarlo (GET)
const leer = await fetch(`https://api.imdica.es/productos/${producto.id}`, {
  headers: { 'Authorization': 'Bearer ABC123' }
});
const data = await leer.json();
// { id: 12345, nombre: '...', precio: 23.5, stock: 47 }

Fíjate: misma URL base (/productos) usada con verbos distintos para operar sobre el mismo concepto.

Errores comunes

• Meter verbos en la URL: /getUser, /createUser, /deleteUser. Eso no es REST, es RPC disfrazado. La URL debe ser un sustantivo y el método HTTP el verbo.
• Usar siempre 200 OK: REST aprovecha la riqueza de códigos HTTP. Si creas algo nuevo, devuelve 201 Created. Si no encuentras, 404. Si el usuario no tiene permiso, 403. Esto facilita debugging y permite a clientes genéricos reaccionar correctamente.
• No versionar la API: el día que tengas que cambiar el formato de respuesta, romperás todos los clientes. Versiona desde el principio (/v1/productos).
• REST puro extremo: HATEOAS (que las respuestas incluyan los links a las siguientes acciones posibles) es parte de REST pero casi nadie lo implementa al 100%. No te obsesiones con el dogma — REST pragmático funciona.
• Confundir REST con JSON: REST no obliga a JSON; podrías devolver XML o lo que quieras. JSON ganó por costumbre y simplicidad, pero técnicamente no es lo que define REST.

Cuándo usar REST

REST es la opción por defecto cuando:

• Construyes una API pública que muchos clientes distintos van a consumir
• Tus recursos son fácilmente identificables (entidades CRUD: usuarios, productos, pedidos...)
• Quieres que clientes nuevos puedan integrarse rápido sin documentación profunda (los verbos HTTP son universales)
• Necesitas que las respuestas se cacheen en CDNs / proxies / browsers

Considera alternativas cuando:

• Tus clientes necesitan datos muy estructurados con muchas relaciones (mejor GraphQL)
• Latencia crítica entre microservicios internos (mejor gRPC)
• Comunicación bidireccional en tiempo real (mejor WebSocket)

Referencias

• Roy Fielding — Architectural Styles and the Design of Network-based Software Architectures (PDF) — la tesis original que define REST
• restfulapi.net — tutorial de referencia
• Stripe API — uno de los mejores ejemplos de diseño REST en producción