¿Qué es REST?

REST (Representational State Transfer) es un estilo arquitectónico, no un protocolo. Define un conjunto de restricciones sobre cómo deben comportarse los servicios web. Cuando una API sigue estas restricciones, la llamamos RESTful. La idea clave es simple: un cliente envía una solicitud a una URL que representa un recurso, y el servidor responde con una representación de ese recurso, generalmente JSON.

Las seis restricciones que definen REST son: separación cliente-servidor, ausencia de estado, cacheabilidad, interfaz uniforme, sistema en capas y código bajo demanda (opcional). En la práctica, las que más importan en el día a día son la ausencia de estado y la interfaz uniforme. Ausencia de estado significa que cada solicitud debe contener toda la información necesaria para procesarla; el servidor no almacena estado de sesión entre solicitudes. Interfaz uniforme significa usar métodos HTTP estándar y patrones de URL predecibles.

Métodos HTTP y su significado

Los métodos HTTP le indican al servidor qué acción realizar sobre un recurso. Cada método tiene un significado semántico específico que debes respetar; ignorarlo lleva a APIs confusas y difíciles de consumir.

GET recupera un recurso sin efectos secundarios. POST crea un nuevo recurso. PUT reemplaza un recurso existente por completo. PATCH actualiza parcialmente un recurso.

Aquí se muestra cómo se mapean a un recurso típico de usuarios:

GET    /users        → list all users
GET    /users/42     → get user with id 42
POST   /users        → create a new user
PUT    /users/42     → replace user 42 entirely
PATCH  /users/42     → update specific fields of user 42
DELETE /users/42     → delete user 42

GET y DELETE son idempotentes: llamarlos varias veces produce el mismo resultado. PUT también es idempotente. POST no lo es: llamarlo dos veces generalmente crea dos recursos.

Códigos de estado HTTP

Los códigos de estado le indican al cliente qué ocurrió. Se agrupan en cinco clases: 1xx informativo, 2xx éxito, 3xx redirección, 4xx error del cliente, 5xx error del servidor. Los que usarás con más frecuencia en el desarrollo de APIs son:

200 OK — la solicitud fue exitosa y hay un cuerpo de respuesta. Úsalo para respuestas exitosas de GET y PATCH.

201 Created — un recurso fue creado con éxito. Úsalo después de un POST exitoso. Incluye una cabecera Location que apunte al nuevo recurso.

204 No Content — éxito, pero sin cuerpo para devolver. Úsalo para DELETE.

400 Bad Request — el cliente envió datos inválidos (campos faltantes, tipos incorrectos, fallos de validación).

401 Unauthorized — la solicitud carece de credenciales de autenticación válidas.

403 Forbidden — el cliente está autenticado pero no tiene permiso.

404 Not Found — el recurso no existe.

409 Conflict — la solicitud entra en conflicto con el estado actual (por ejemplo, crear un usuario con un email que ya existe).

422 Unprocessable Entity — la solicitud está bien formada pero falla en la validación semántica.

500 Internal Server Error — algo salió mal en el servidor. Nunca expongas trazas de pila aquí en producción.

Un ejemplo concreto en un manejador de Express:

app.post('/users', (req, res) => {
  const { email, name } = req.body;

  if (!email || !name) {
    return res.status(400).json({ error: 'email and name are required' });
  }

  // imagine createUser() saves to a database and returns the new record
  const user = createUser({ email, name });

  res
    .status(201)
    .location(`/users/${user.id}`)
    .json(user);
});

Cabeceras HTTP en el contexto de APIs

Las cabeceras transportan metadata sobre la solicitud o respuesta. Algunas son esenciales para las APIs REST.

Content-Type declara el formato del cuerpo de la solicitud o respuesta. Para APIs JSON siempre es application/json. Express lo establece automáticamente cuando llamas a res.json(), pero al construir respuestas crías debes establecerlo explícitamente.

Accept le indica al servidor qué formato puede manejar el cliente. Los clientes deben enviar Accept: application/json al llamar a una API JSON.

Authorization transporta credenciales. El patrón más común para APIs REST es la autenticación con token Bearer:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Cache-Control dirige el comportamiento de caché para las respuestas GET. Para datos públicos que raramente cambian, establecer Cache-Control: public, max-age=300 reduce la carga en tu servidor. Para datos sensibles o específicos del usuario, usa Cache-Control: no-store.

En Express puedes leer las cabeceras entrantes mediante req.headers y establecer las salientes mediante res.set():

app.get('/products', (req, res) => {
  const products = getProducts();
  res
    .set('Cache-Control', 'public, max-age=300')
    .json(products);
});

Resumen

REST es un estilo arquitectónico construido sobre comunicación cliente-servidor sin estado con una interfaz uniforme. Los métodos HTTP definen qué acción realizar sobre un recurso: GET lee, POST crea, PUT reemplaza, PATCH actualiza, DELETE elimina. Los códigos de estado comunican el resultado con precisión: 2xx para éxito, 4xx para errores del cliente, 5xx para fallos del servidor. Las cabeceras transportan metadata como tipo de contenido, credenciales de autenticación y directivas de caché. Hacer bien estos fundamentos es lo que separa a una API fácil de integrar de una que obliga a los consumidores a adivinar.