HTTP como contrato
Diseña peticiones y respuestas que le digan al cliente exactamente qué pasó.
AL TERMINAR, PODRÁS
- Identificar métodos, rutas, cabeceras y cuerpos
- Distinguir aceptación de finalización
- Definir el comportamiento de reintento de una API asíncrona
Descripción del diagrama: 1. Cliente → API: POST /jobs {payload}; 2. API → Cliente: 202 Accepted · id=42; 3. API → Worker: trabajo 42 en cola; 4. Cliente → API: GET /jobs/42; 5. API → Cliente: 200 {"status": "running"}
Una petición pide una operación
HTTP transporta un método, un destino, cabeceras (headers) y a veces un cuerpo (body).
El método aporta significado: GET obtiene una representación, mientras que POST suele enviar datos para que se procesen. Una respuesta incluye un código de estado, cabeceras y contenido opcional. Diseña todo esto en conjunto, en lugar de tratar la API como una función remota con strings arbitrarios.
En Relay, POST /jobs acepta un trabajo y GET /jobs/{id} obtiene su estado. Valida el tipo de contenido y la forma del cuerpo antes de crear trabajo, y devuelve un identificador que el cliente pueda usar después.
Aceptado no es terminado
Una API de colas suele avisar que el trabajo fue aceptado antes de que esté terminado.
Una respuesta 202 puede expresar esa diferencia, mientras su cuerpo o un enlace le dicen al cliente cómo consultar el progreso. Especifica si aceptar significa almacenamiento duradero o solo memoria; esas promesas son distintas si el proceso se cae. Un timeout (tiempo de espera agotado) es ambiguo: el servidor pudo haber aceptado el trabajo aunque el cliente no recibió respuesta.
Esa ambigüedad es la razón por la que una operación de creación que se puede reintentar suele necesitar una clave de idempotencia (idempotency key) explícita.
Haz los errores útiles y estables
Usa los códigos de estado de forma coherente e incluye un código de error estructurado más un mensaje seguro y accionable.
Separa entrada mal formada, falta de autorización, recursos inexistentes, conflictos y sobrecarga temporal. No filtres trazas internas ni credenciales en las respuestas. Define límites de tamaño del cuerpo y de frecuencia de peticiones para que un solo cliente no agote el servicio.
Un cliente debería saber si tiene que corregir su entrada, autenticarse, esperar o dejar de reintentar. Las pruebas (tests) de contrato pueden verificar estos comportamientos sin depender del enrutamiento interno del framework.
ERROR FRECUENTE
Responder con éxito antes del punto de durabilidad prometido crea una violación silenciosa del contrato si el proceso se cae justo después.
INTÉNTALO TÚ
Especifica ejemplos de petición y respuesta para crear un trabajo y consultar su estado. Explica qué debería hacer un cliente después de un timeout al crearlo.
Decide en el laboratorio.
El checkpoint de dos preguntas, tus notas y tu progreso guardado están en el laboratorio. Gratis y sin cuenta.
Abrir en el laboratorio ↗CONÉCTALO CON RELAY
Escribe el contrato HTTP de Relay, incluyendo las respuestas de trabajo aceptado, los errores de validación, la consulta periódica (polling) y la promesa exacta de durabilidad.