Operaciones de larga duración: 202 Accepted y un recurso de estado

Qué es

RFC 9110 (citada) define 202 (Accepted) como deliberadamente no comprometedor: la solicitud se ha aceptado para su procesamiento pero el procesamiento no se ha completado, todavía podría rechazarse más tarde, y HTTP no tiene ningún mecanismo para reenviar un código de estado de una operación asíncrona. La representación enviada con un 202 debería describir el estado actual de la solicitud y apuntar a (o incluir) un monitor de estado. El AIP-151 de Google (citado) convierte ese monitor en un recurso de primera clase: los métodos que pueden tardar un tiempo considerable devuelven una Operation con un nombre, un indicador done, metadata para el progreso y los fallos parciales, y al completarse, o bien error o bien response. Su regla general es que el trabajo de más de unos 10 segundos justifica el patrón y que las operaciones pueden caducar, sugiriendo 30 días.

Por qué importa

Bloquear una conexión durante minutos falla en todas las capas: los proxies cortan las conexiones inactivas, los clientes expiran y reintentan, y un trabajo no idempotente reintentado se ejecuta dos veces. Un recurso de operación explícito permite al cliente desconectarse, sondear y recuperarse tras su propio reinicio, y da al servidor un único lugar donde registrar el resultado.

Cómo aplicarlo

• Devolver 202 Accepted con un Location (o un enlace en el cuerpo) a /operations/{id} e incluir la representación de la operación en el cuerpo, de modo que el cliente no necesite una segunda solicitud inmediata.
• Modelar la operación con done, metadata (progreso, recuentos, errores no fatales) y exactamente uno de error o response una vez terminada; usar la misma forma de error que los fallos síncronos.
• Aceptar una clave de idempotencia proporcionada por el cliente en la solicitud inicial, de modo que un reintento tras un 202 perdido devuelva la misma operación en lugar de iniciar una segunda.
• Admitir el sondeo con indicaciones Retry-After; ofrecer un webhook para los clientes que puedan recibir uno, pero mantener el sondeo como alternativa de respaldo.
• Documentar la caducidad: cuánto tiempo permanece recuperable el resultado y qué devuelve un GET sobre una operación caducada.
• Para los recursos creados de forma asíncrona, dejar que List y Get muestren el recurso con un estado que lo marque como todavía no utilizable (AIP-151).
• Decidir cómo se comportan las operaciones paralelas sobre un mismo recurso: encolarlas, o rechazar con un error de conflicto que nombre la operación en curso.

Trampas

Devolver 202 y luego procesar de forma síncrona de todos modos. Cambiar el tipo de resultado de una operación existente, lo que el AIP-151 clasifica como un cambio incompatible. Usar 200 con un cuerpo «pending», lo que hace que las cachés y los clientes traten el trabajo como terminado. Perder los registros de operación al reiniciar, de modo que el cliente nunca pueda conocer el resultado. Endpoints de sondeo sin límites de tasa.

Responder de forma síncrona cuando el trabajo es rápido

Decidir por solicitud, no por tipo de operación, cuando la latencia es bimodal. Ejecutar el trabajo durante un tiempo acotado y, si se completa, responder 200 o 201 con el resultado; en caso contrario, responder 202 con el recurso de operación. RFC 7240 da voz al cliente: Prefer: wait=N acota cuánto tiempo esperará, Prefer: respond-async solicita directamente la vía 202, y el servidor informa de lo que respetó en Preference-Applied. Documentar ambas formas de respuesta para la operación y dejar que el asistente de espera del SDK las normalice, de modo que quien llama vea un único tipo de resultado. Reservar el diseño siempre-202 para el trabajo que siempre es largo.