Cómo funcionan las API REST: la ida y vuelta de una petición

Cómo funcionan las API REST: la ida y vuelta de una petición

El lienzo interactivo de FlowJam de esta explicación: cada carril, cada fila y cada flecha de arriba forma parte de un diagrama real de QueryChart que puedes abrir y editar.

Cómo leer este diagrama

• Lee las tres columnas de izquierda a derecha: Petición, Procesamiento en el servidor, Respuesta.
• La fila del cliente y la del servidor se alternan, así que cada flecha es o bien el cliente enviando algo o bien el servidor decidiendo algo.
• La decisión «¿Es válida la petición?» alimenta o el camino feliz o el final de rechazo: los dos resultados que puede tener cualquier llamada a una API.

La petición

«El cliente construye una petición HTTP (método, URL, cabeceras, cuerpo)» es el comienzo de toda interacción REST. El método es el verbo —GET lee, POST crea, PUT reemplaza, PATCH actualiza, DELETE elimina— y la URL nombra el recurso, así que /users/42 es la petición para leer un usuario. «El cliente envía la petición por HTTPS» es el transporte: REST viaja sobre HTTP, y HTTPS mantiene privada la conversación sobre la misma infraestructura de internet que dibujan los otros diagramas.

El trabajo del servidor

«El servidor enruta la URL al handler correspondiente» asocia la petición con el código —el handler es la función que atiende esa ruta—, y «¿Es válida la petición?» es la puerta: aquí ocurren la autenticación (quién eres), la autorización (si tienes permiso) y la validación del cuerpo, y los fallos van al final de rechazo «El servidor devuelve 400 / 401 / 403». «El handler ejecuta la lógica de negocio» y «El servidor lee o escribe el recurso en la base de datos» son el trabajo de verdad: la parte que el cliente nunca ve.

La respuesta

«El servidor construye la respuesta con un código de estado y un cuerpo JSON» es el contrato en forma legible por máquinas: 200 para éxito, 201 para creado, 404 para no encontrado, 500 para un fallo del servidor. «El cliente recibe la respuesta y la analiza» y «El cliente renderiza el resultado para el usuario» cierran el círculo: la ida y vuelta termina donde empezó, en el cliente, y por eso mismo el diagrama vuelve a la fila del cliente.

Relaciones clave y conclusiones

• REST es un contrato en HTTP: los métodos son verbos, las URL son recursos y los códigos de estado son el resultado legible por máquinas.
• El cliente es sin estado: cada petición lleva todo lo que el servidor necesita, así que no hace falta ninguna sesión compartida.
• La validación es la frontera de seguridad; una petición no válida se rechaza antes de ejecutar cualquier lógica de negocio.
• La respuesta se define primero por su código de estado y después por su cuerpo.
• El tráfico REST viaja sobre la misma infraestructura de DNS, HTTPS e internet que dibujan los otros diagramas de tecnología.

Cuándo usar este diagrama

• Enseñar el modelo de método, URL y código de estado de HTTP a los ingenieros antes de que diseñen su primer endpoint.
• Revisar el contrato de una API —¿los errores son códigos de estado o un 200 con un indicador?— frente a la convención REST.
• Anclar una conversación sobre idempotencia y caché en cómo se construyen y se validan las peticiones de verdad.

Cómo funciona

1. Lleva tus propios endpoints a la caja de la petición

   Añade notas con tus métodos y rutas reales —GET /orders, POST /payments— para que el diagrama documente la superficie de tu API.

2. Nombra tus códigos de estado

   En el paso de la respuesta, anota los códigos que devuelve de verdad tu API para cada resultado y añade los que use tu contrato más allá del 200 y el 400.

3. Añade la autenticación

   Inserta el paso del token entre el cliente y la puerta de validación —un token JWT o de OAuth en la cabecera Authorization— para mostrar por dónde entra la identidad en la petición.

4. Dibuja las ramas de reintento y de fallo

   Añade finales explícitos para los fallos de red, la limitación de tasa y los errores del servidor, cada uno con el comportamiento del cliente (reintento, backoff, estado de error) que dispara.

Preguntas frecuentes

¿Qué es una API REST?

Una API REST es un conjunto de endpoints HTTP que exponen los recursos de un sistema. Los clientes actúan sobre los recursos con métodos HTTP —GET para leer, POST para crear, PUT o PATCH para actualizar, DELETE para eliminar— y el servidor responde con un código de estado y una representación, normalmente JSON. REST es un estilo más que un estándar, y su valor está en que cualquier cliente que hable HTTP puede usarla.

¿Cuál es la diferencia entre GET, POST, PUT y DELETE?

Son los verbos del contrato REST. GET lee un recurso y no debería tener efectos secundarios. POST crea un recurso nuevo y devuelve su identidad. PUT reemplaza un recurso entero y es idempotente: repetirlo no cambia nada más. PATCH aplica una actualización parcial. DELETE elimina un recurso. Juntos, el verbo y la URL nombran la acción completa, y por eso la caja de la petición del diagrama destaca primero el método.

¿Por qué son importantes los códigos de estado en REST?

Porque son el resultado de la petición legible por máquinas. Un cliente puede ramificarse según el código de estado sin analizar el cuerpo: 2xx éxito, 4xx error del cliente, 5xx error del servidor. Las API que devuelven un 200 con un indicador de error en el cuerpo rompen este contrato y obligan a cada cliente a tratar la respuesta como un caso especial.

¿Qué hace que una API sea «RESTful»?

La lista práctica: recursos nombrados por URL, acciones expresadas como métodos HTTP, peticiones sin estado (cada una lleva todo lo que el servidor necesita), respuestas que usan bien los códigos de estado y, a menudo, hipermedia o URL versionadas. El lienzo modela la ida y vuelta —petición, validación, procesamiento, respuesta—, que es la forma que comparte todo intercambio RESTful.

Edita este diagrama en QueryChart (FlowJam)

Abre este mismo lienzo de REST como tu propio diagrama, renombra el cliente y el servidor con tus servicios y anota tus endpoints.

Edita este diagrama en QueryChart (FlowJam)