REST

Definición

Imagina que entras a un restaurante. El menú te muestra qué platos hay disponibles (recursos), usas verbos estándar para interactuar (ordenar, modificar, cancelar), y no esperas que el mesero recuerde tu pedido de la semana pasada - cada visita es independiente. Eso es esencialmente cómo funciona REST.

REST (Representational State Transfer) es un estilo arquitectónico para diseñar APIs que aprovecha la forma natural en que funciona la web. En lugar de inventar métodos personalizados como “getUser” o “createOrder”, usas los verbos HTTP que ya existen: GET para obtener datos, POST para crear, PUT para actualizar, DELETE para eliminar. Los datos se organizan alrededor de “recursos” (usuarios, productos, pedidos) con URLs claras como /users/123 o /orders/456.

¿Por qué se volvió tan popular? Porque es simple y predecible. Si sabes cómo funciona una API REST, puedes adivinar cómo funcionará otra. GET /users probablemente lista usuarios. DELETE /users/123 probablemente borra al usuario 123. Esta consistencia significa menos documentación que leer, menos sorpresas, y más fácil integración. Es como si todos los restaurantes del mundo usaran el mismo formato de menú - una vez que aprendes a leerlo, puedes pedir en cualquier lugar.

Ejemplo

API de una Red Social: Cuando tu app de Twitter muestra tu timeline, hace GET /api/tweets. Para publicar un tweet, envía POST /api/tweets con el contenido. Para dar like, POST /api/tweets/123/likes. Para borrar tu tweet, DELETE /api/tweets/456. Cada acción mapea claramente a un verbo HTTP y un recurso.

E-commerce como Amazon: Navegando productos es GET /products. Ver un producto específico es GET /products/abc123. Agregar al carrito es POST /cart/items. Modificar cantidad es PATCH /cart/items/xyz. Checkout es POST /orders. La estructura entera del sitio se puede entender a través de estos patrones REST.

API Bancaria: Ver tus cuentas es GET /accounts. Ver transacciones de una cuenta es GET /accounts/123/transactions. Transferir dinero es POST /transfers. El patrón es el mismo aunque los datos son completamente diferentes.

Google Maps: Buscar lugares es GET /places?query=cafeteria. Obtener detalles de un lugar es GET /places/ChIJ.... Agregar una reseña es POST /places/ChIJ.../reviews. Incluso servicios complejos como mapas siguen los mismos patrones REST.

Analogía

El Sistema del Menú de Restaurante: En un restaurante REST, el menú (API) muestra claramente los platos disponibles (recursos). Usas verbos estándar: “quiero” (GET), “dame uno nuevo” (POST), “cambia esto” (PUT), “quita esto” (DELETE). El mesero no necesita recordar tus pedidos anteriores - cada interacción es completa en sí misma. No hay métodos mágicos como “hazmeElEspecial” - todo sigue el formato estándar.

El Sistema de Biblioteca: En una biblioteca, tienes recursos claros (libros, usuarios, préstamos). Para ver qué libros hay, consultas el catálogo (GET /books). Para sacar un libro, creas un préstamo (POST /loans). Para devolver, borras el préstamo (DELETE /loans/123). El bibliotecario no recuerda tu historial entre visitas - cada transacción es independiente y contiene toda la información necesaria.

Correos y Paquetería: El sistema postal es RESTful. Enviar algo es POST (crear un envío). Rastrear es GET (obtener estado). Cancelar un envío es DELETE. Modificar la dirección es PUT. No importa si estás enviando cartas o paquetes gigantes - los verbos son los mismos. Y Correos no “recuerda” que enviaste algo ayer - cada envío es independiente.

Las Máquinas Expendedoras: Una máquina expendedora es sorprendentemente RESTful. Los productos son recursos con identificadores claros (A1, B2). Seleccionar es GET (ver qué hay). Insertar dinero y seleccionar es POST (comprar). La máquina no recuerda tu última compra ni te ofrece descuentos basados en historial - cada transacción es sin estado e independiente.

Code Example

// Diseño de [API RESTful](https://reference.apios.info/es/terms/restful-api/)
// Recursos como sustantivos, métodos HTTP como verbos
GET    /api/v1/users          // Listar usuarios
GET    /api/v1/users/123      // Obtener usuario específico
POST   /api/v1/users          // Crear usuario
PUT    /api/v1/users/123      // Actualizar usuario (completo)
PATCH  /api/v1/users/123      // Actualizar parcialmente
DELETE /api/v1/users/123      // Eliminar usuario

// Respuesta RESTful típica
[HTTP/1.1](https://reference.apios.info/es/terms/http-1-1/) 200 OK
Content-Type: application/json
{
  "id": 123,
  "name": "Alicia",
  "email": "[email protected]"
}

Diagram

graph LR
C[Cliente] -->|Petición HTTP| S[Servidor]
S -->|Respuesta HTTP| C
S --- CS[Cliente-Servidor]
S --- ST[Sin Estado]
S --- CA[Cacheable]
S --- LS[Sistema en Capas]
S --- UI[Interfaz Uniforme]

Notas de Seguridad

Mejores Prácticas

1. Usa sustantivos para nombres de recursos, no verbos (/users no /getUsers)
2. Usa sustantivos en plural para colecciones (/users no /user)
3. Usa métodos HTTP correctamente (GET para leer, POST para crear)
4. Retorna códigos de estado apropiados (201 para crear, 204 para eliminar)
5. Soporta filtrado, ordenamiento y paginación para colecciones
6. Versiona tu API desde el inicio

Errores Comunes

Usar verbos en URLs (/getUsers en lugar de /users), usar POST para todo, retornar 200 para errores, no soportar negociación de contenido, ignorar cabeceras de caché, sobre-obtener o sub-obtener datos.

Standards & RFCs