Qué es REST y cómo organiza las APIs web

REST en APIs web explicado con claridad: domina los principios que vuelven predecibles los servicios, desde recursos y HTTP hasta idempotencia, representaciones en JSON y códigos de estado como 200, 201 y 204. Con estas convenciones, integrar y diseñar será más simple y confiable.

¿Qué es REST y cómo ordena las APIs?

REST significa Representational State Transfer: un conjunto de reglas que estandariza cómo construir una API para que sea fácil de entender. Funciona como reglas de tránsito: todos reconocen la intención. En lugar de caos, hay convenciones claras.

• Todo gira en torno a recursos: usuarios, productos, pedidos, mensajes, libros.
• Cada recurso tiene una dirección única, como una dirección postal.
• Las convenciones evitan ambigüedades: intuyes qué hace cada solicitud.

Ejemplo de rutas de recursos.

GET /usuarios
GET /libros

¿Cómo se organiza todo en recursos?

Un recurso es cualquier entidad que puedas nombrar. Se accede con una dirección única. Pensar en direcciones ayuda a visualizar la estructura.

• Usuarios, productos o libros son recursos distintos.
• Cada elemento tiene su identificador único.

GET /usuarios
GET /usuarios/123

¿Qué es una representación en JSON?

Cuando pides un recurso, recibes una representación del estado en ese momento, normalmente en JSON. No es el objeto interno del servidor: es lo que necesitas como consumidor.

• Representa un momento específico del recurso.
• El servidor envía solo lo necesario para el cliente.

¿Qué hacen los métodos HTTP en REST?

Cada verbo de HTTP tiene un propósito claro. Esta consistencia permite predecir resultados sin leer documentación.

• GET: obtener información. No modifica nada.
• POST: crear un recurso nuevo.
• PUT: actualizar un recurso reemplazándolo por completo.
• PATCH: modificar parcialmente un recurso existente.
• DELETE: eliminar un recurso.

Ejemplos típicos.

GET /usuarios              # lista usuarios
POST /usuarios             # crea un usuario
PUT /usuarios/123          # reemplaza al usuario 123
PATCH /usuarios/123        # cambia campos del usuario 123
DELETE /usuarios/123       # elimina al usuario 123

¿Qué implica la idempotencia en GET, PUT y DELETE?

La idempotencia significa que repetir la misma operación produce el mismo resultado.

• GET es idempotente: pedir lo mismo varias veces da lo mismo.
• PUT es idempotente: actualizar con los mismos datos no cambia el estado tras la primera vez.
• DELETE es idempotente: eliminar algo ya eliminado no altera nada.

¿Por qué POST no es idempotente?

Cada POST crea un recurso nuevo. Repetir la misma solicitud genera múltiples creaciones, por eso no es idempotente.

¿Cómo responden las APIs REST con códigos HTTP?

Las APIs REST usan códigos de estado HTTP de forma consistente para comunicar resultados.

• 2xx: todo salió bien.
• 4xx: el cliente hizo algo mal.
• 5xx: el servidor tiene problemas.

Códigos esperados según la operación.

• 200 en un GET cuando el recurso existe.
• 201 al crear con POST.
• 204 al eliminar con DELETE exitoso.

¿Por qué REST es sin estado en cada petición?

Cada petición debe incluir toda la información necesaria. El servidor no recuerda solicitudes previas: cada interacción es como presentarte por primera vez.

• No puedes decir: dame lo mismo de la vez pasada.
• Debes especificar exactamente qué necesitas en cada solicitud.

¿Tienes dudas o ejemplos que quieras validar? Compártelos y los revisamos juntos.