Endpoints masivos y el reporte de fallos parciales

Qué es

Un endpoint masivo recibe muchos elementos en una sola solicitud: crear 500 contactos, actualizar 50 precios, o, como en el procesamiento por lotes en JSON de Microsoft Graph (citado), envolver hasta 20 subsolicitudes arbitrarias en una única llamada HTTP. Existen dos comportamientos. Atómico: se aplican todos los elementos o ninguno. Éxito parcial: el servidor aplica lo que puede y reporta cada fallo. El AIP-233 de Google (citado) exige que una creación por lotes síncrona sea atómica, y su justificación explica por qué: un estado OK implica que todo funcionó, de modo que añadir después información de fallo parcial a una respuesta síncrona cambiaría en silencio lo que asumen los clientes existentes. Los lotes asíncronos, que devuelven una operación, pueden admitir el éxito parcial y reportar los fallos como un mapa del índice de la solicitud a un objeto de estado; los errores transitorios que el servidor va a reintentar no deben aparecer ahí, y cuando todos los elementos fallan, la propia operación se marca como fallida.

Por qué importa

Los clientes reintentan las solicitudes masivas. Con semántica atómica, un reintento es seguro; con éxito parcial, un reintento vuelve a enviar elementos ya aplicados a menos que el cliente pueda distinguir cuáles fallaron. El formato de reporte determina si los reintentos crean duplicados.

Cómo aplicarlo

• Elegir un comportamiento por endpoint, documentarlo y no cambiarlo nunca en el mismo lugar; pasar de atómico a éxito parcial requiere una nueva versión o un indicador explícito cuyo valor por defecto sea el comportamiento anterior (AIP-233 describe return_partial_success).
• Reportar el estado a nivel de solicitud por separado de los resultados por elemento. Graph devuelve 200 para cualquier lote analizable, da a cada subrespuesta su propio status, e indica que el 200 del lote no significa que las solicitudes individuales tuvieran éxito.
• Referenciar los fallos por índice, o por un id proporcionado por el cliente que debe ser único dentro del lote, y reutilizar la forma de error de un único elemento para que las rutas de código del cliente se compartan.
• Limitar el tamaño del lote e indicar ese límite. Aplicar la autorización, la validación y los límites de tasa por elemento; Graph evalúa cada solicitud individualmente frente a la limitación de tasa y falla esa solicitud con 429.
• Admitir el orden solo cuando sea necesario; el dependsOn de Graph falla las dependientes con 424 (Failed Dependency) cuando falla un prerrequisito.
• El 207 (Multi-Status) de WebDAV (RFC 4918, citado) existe para múltiples estados por recurso, pero los clientes y proxies generales no lo conocen; un cuerpo JSON con el estado por elemento resulta más portable.

Trampas

Un endpoint de éxito parcial que devuelve un simple 200 y entierra los fallos en un registro. Devolver las cargas útiles de la solicitud dentro de las entradas de error, algo que AIP-233 rechazó por motivos de sensibilidad de los datos. Lotes cuyo procesamiento supera el tiempo límite de la puerta de enlace: a partir de cierto tamaño, el trabajo masivo pertenece a una operación de larga duración.