Planteamiento y alcance
Una API de escritura por lotes atiende a clientes con diferentes objetivos de ancho de banda y latencia: algunos solo necesitan el estado, algunos necesitan una representación completa del recurso y otros esperarán unos segundos para evitar el sondeo (polling). Utilizando RFC 7240, diseñe el encabezado de solicitud Prefer, el encabezado de respuesta Preference-Applied, el manejo de errores, el almacenamiento en caché y el comportamiento de fallback.
Prefer es una preferencia de solicitud, no un mandato para el servidor. Esta pregunta evalúa la semántica del protocolo y los contratos de la API; no asume que todos los proxies preserven los encabezados de preferencias.
Qué evalúa el entrevistador
- Si distingue entre una preferencia del cliente y una promesa del servidor, y si reporta lo que realmente se aplicó.
- Si utiliza
return=minimal,return=representation,respond-asyncywaitcorrectamente. - Si tiene en cuenta las variantes de respuesta,
Vary, las claves de caché y la compatibilidad con proxies. - Si los reintentos, las claves de idempotencia y el estado de los trabajos asíncronos permanecen seguros cuando no se respeta una preferencia.
Preguntas de aclaración
- ¿Es la API una lectura segura o una escritura con efectos secundarios, y cuenta ya con una clave de idempotencia?
- ¿Cuáles son el tamaño, el costo de generación y la espera máxima para una representación completa?
- ¿Pueden los clientes aceptar 202 y un recurso de estado, sondeo (polling) o un callback?
- ¿Reenviarán los intermediarios (middleboxes) Prefer y se pueden compartir las cachés?
- ¿Qué campos estables deben ver los clientes cuando no se respeta una preferencia?
Una respuesta de 30 segundos
“Prefer expresa una preferencia del cliente que un servidor puede ignorar o aplicar parcialmente; Preference-Applied reporta lo que se aplicó. Una escritura puede usar return=minimal para reducir la respuesta, un invocador síncrono puede solicitar return=representation y una operación larga puede usar respond-async con un wait acotado. Diseñaría las claves de idempotencia, un recurso de estado 202, Vary para la caché y el fallback del cliente en conjunto: sin Preference-Applied, procese la respuesta por defecto y nunca asuma que la preferencia tuvo éxito.”
Diseño paso a paso
1. Tratar la preferencia como una negociación que se puede ignorar
RFC 7240 define el encabezado de solicitud Prefer y el encabezado de respuesta Preference-Applied. Un servidor puede rechazar una preferencia, por lo que el cuerpo y el código de estado necesitan un contrato por defecto estable. Un cliente no debe omitir el procesamiento simplemente porque envió Prefer.
2. Elegir los tokens de preferencia correctos
return=minimal se adapta a una escritura que solo necesita confirmación; return=representation se adapta a un invocador síncrono que necesita el recurso actualizado. respond-async indica que el cliente acepta procesamiento asíncrono, mientras que wait=n proporciona un presupuesto de espera. Estas son sugerencias, no una garantía de SLA.
3. Confirmar el resultado en la respuesta
Envíe Preference-Applied cuando se utilice una preferencia. Cuando no se use, el encabezado puede estar ausente y se aplica el contrato por defecto. Una ruta asíncrona devuelve 202, un URI de estado y un ID rastreable; después de que expire un presupuesto de espera síncrona, la operación debe seguir siendo consultable en lugar de provocar que el cliente vuelva a enviar un efecto secundario.
POST /v1/imports HTTP/1.1
Prefer: return=minimal, respond-async, wait=3
Idempotency-Key: imp-8f2
HTTP/1.1 202 Accepted
Preference-Applied: respond-async
Location: https://api.example/imports/jobs/42
Cache-Control: no-store4. Manejar variantes de caché
Si una representación GET segura varía con Prefer, declare Vary correctamente o mantenga las respuestas dependientes de preferencias fuera de las cachés compartidas. Las escrituras normalmente usan no-store. Un recurso de estado asíncrono debe definir almacenamiento en caché breve, ETags o condiciones explícitas de sondeo para que un intermediario no devuelva un progreso desactualizado.
5. Preservar la idempotencia y el fallback
Prefer no cambia la semántica de la operación, por lo que los reintentos aún necesitan idempotencia. Utilice una clave de idempotencia o de desduplicación de negocio para las escrituras. Si un cliente ve un 202, un tiempo de espera agotado o no ve Preference-Applied, debe consultar el trabajo o seguir el contrato de respuesta por defecto en lugar de crear el recurso nuevamente.
6. Establecer observabilidad y límites
Registre los tokens de preferencias, si se aplicaron, la duración de la espera, el tamaño de la respuesta, la tasa de 202 y la ruta del proxy. Limite wait, rechazando o truncando valores excesivos. Ignore y registre las preferencias desconocidas en lugar de convertir cadenas de cliente arbitrarias en rutas de ejecución costosas.
Respuesta modelo de alta calidad
“Trataría Prefer como una preferencia del cliente que se puede ignorar, no como una promesa. Una escritura tiene por defecto un estado estable; un cliente que desea una respuesta pequeña envía return=minimal, uno que necesita el recurso envía return=representation y un trabajo largo utiliza respond-async con un wait acotado. El servidor envía Preference-Applied solo cuando aplica la preferencia; un resultado asíncrono es 202 con Location y un ID de trabajo. Las escrituras usan claves de idempotencia, las respuestas usan no-store donde corresponda y las diferencias de representación se aíslan con Vary o políticas de caché. Sin Preference-Applied, el cliente sigue el analizador por defecto y consulta el trabajo, nunca duplicando un efecto secundario.”
Errores comunes
- Tratar Prefer como obligatorio → los servidores y proxies pueden ignorarlo → utilice un contrato por defecto y Preference-Applied.
- Tratar la espera como una garantía de finalización → los trabajos largos aún pueden excederla → limite el presupuesto y exponga un recurso de estado 202.
- Reenviar después de un tiempo de espera asíncrono agotado → resulta en efectos secundarios duplicados → utilice una clave de idempotencia y consulte primero.
- Ignorar las variantes de caché → los clientes reciben una representación incompatible → configure Vary o aísle la caché.
- Ejecutar preferencias arbitrarias desconocidas → los atacantes pueden amplificar el costo de recursos → ignore, registre y limite los tokens.
Preguntas de seguimiento y respuestas
¿La ausencia de Preference-Applied significa que la solicitud falló?
No. El servidor puede elegir su comportamiento por defecto o ignorar la preferencia. El cliente debe procesar el contrato por defecto estable y considerarlo un fallo solo cuando el protocolo o el estado del negocio indiquen que falló.
¿Puede cada escritura usar return=minimal?
No. Solo indica que el cliente no necesita una representación completa. Si el cliente necesita una versión generada por el servidor, un resumen (digest) o un enlace siguiente, debe solicitar la representación u obtener el recurso en lugar de inferir campos a partir de una respuesta vacía.
¿Hace wait=5 que el servidor se bloquee durante cinco segundos?
No se deduce ninguna garantía estricta. Es la preferencia de espera máxima del cliente; el servidor puede terminar antes, ignorarla o cambiar a asíncrono. Los tiempos de espera del servidor, los límites de concurrencia y los presupuestos de recursos siguen aplicando.