Prompt y alcance
Una API acepta JSON y CBOR para POST y JSON Patch para PATCH. Los clientes reciben 415 tras enviar un Content-Type incorrecto, una codificación de contenido errónea o un formato de documento de patch no admitido. Diseña la clasificación del servidor, los encabezados de respuesta, el cuerpo del error, la recuperación del cliente y la evolución de versiones.
Esta es una pregunta sobre el contrato de una API de backend. Los media types y formatos son supuestos, no afirmaciones sobre frecuencia.
Qué está evaluando el entrevistador
- Si separas Content-Type y Content-Encoding de la solicitud respecto al Accept de la respuesta.
- Si utilizas 415 de forma precisa en lugar de etiquetar cada error de análisis sintáctico de esa manera.
- Si expones la capacidad de PATCH con Accept-Patch manteniendo la compatibilidad.
- Si el error es procesable sin reintentos automáticos no seguros.
Preguntas aclaratorias para hacer
- ¿El 415 es causado por el media type, el content encoding o la capacidad del método?
- ¿Puede el cliente volver a codificar el cuerpo y existe un ID de solicitud estable?
- ¿Qué formatos de patch y condiciones de versión de recursos son compatibles?
- ¿Puede una pasarela (gateway) reescribir el Content-Type, la codificación o el cuerpo del error?
- ¿Cómo se desplegará un nuevo media type sin romper a los clientes antiguos?
Una respuesta de 30 segundos
“415 significa que el método de destino rechaza el formato de la representación de la solicitud. El servidor analiza Content-Type, los parámetros y Content-Encoding, luego selecciona un analizador según la capacidad del método y del recurso. Accept describe los formatos de respuesta que el cliente desea; no describe el documento de patch que envió. Un recurso PATCH puede anunciar los tipos de documento soportados con Accept-Patch. El error devuelve un código estable, los valores recibidos y permitidos, y un ID de solicitud. Reintenta solo tras una recodificación segura y un análisis de repetición.”
Diseño paso a paso
1. Separar la semántica de los tres encabezados
Content-Type describe el media type del cuerpo de la solicitud, Content-Encoding describe la codificación de transferencia y Accept describe las representaciones de respuesta que el cliente puede recibir. El servidor no debe usar Accept para clasificar un documento PATCH ni fusionar descompresión, corrupción y medios no soportados en una sola causa.
2. Mapear la capacidad del método y del recurso
Cada método y recurso declara los media types y parámetros soportados. Por ejemplo, POST acepta application/json y application/cbor, mientras que PATCH acepta un tipo de documento JSON Patch registrado. Comprueba el tipo y la codificación antes de analizar; tras el análisis, continúa ejecutando las validaciones de esquema, autorización y negocio.
PATCH /documents/42 HTTP/1.1
Content-Type: application/json-patch+json
Accept: application/json
Content-Length: 1283. Devolver un 415 preciso
Devuelve 415 con un código de error estable cuando el media type o el content encoding no sean compatibles. Utiliza un error de validación de dominio para sintaxis válida con campos inválidos, y un error de análisis claro para contenido mal formado. Un encabezado de respuesta Accept puede describir las representaciones que el servidor puede devolver; no es una lista de media types de solicitud.
4. Anunciar la capacidad de PATCH
El RFC 5789 define Accept-Patch; un recurso puede declarar los media types de documentos de patch soportados en OPTIONS o en una respuesta exitosa. El cliente puede entonces elegir JSON Patch u otro formato, mientras el servidor sigue verificando la versión del recurso, las rutas y la autorización. El anuncio debe coincidir con el conjunto real de analizadores.
5. Hacer que la recuperación del cliente sea segura
Tras un 415, el cliente lee el código estable y el tipo permitido, vuelve a codificar el cuerpo o selecciona un endpoint compatible. El reintento automático requiere un cuerpo reconstruible, ningún efecto secundario irreversible y la misma clave de idempotencia. No reenvíes un PATCH que pueda haber tenido éxito y no trates 415 como una indisponibilidad temporal.
6. Desplegar y observar los cambios
Implementa un nuevo media type mediante despliegue canary a través de la pasarela, el servidor y el SDK, manteniendo una ventana de compatibilidad para el tipo anterior. Segmenta las métricas por recurso, método, tipo recibido, codificación, versión del cliente y motivo de rechazo. Registra en los logs el ID de solicitud y la versión del analizador, nunca cuerpos con datos sensibles. Compara los encabezados perimetrales (edge) y de la aplicación cuando una pasarela los reescriba.
Respuesta modelo de alta calidad
“Separo los formatos de solicitud y respuesta. El servidor comprueba Content-Type y Content-Encoding según el método y el recurso, analiza únicamente las representaciones soportadas y luego ejecuta la validación de esquema y de negocio; Accept sirve para la negociación de respuesta. Los recursos PATCH anuncian los tipos de documento con Accept-Patch, pero cada solicitud sigue verificando la versión y la autorización. Un cuerpo 415 proporciona un código estable, valores recibidos y permitidos, y el ID de solicitud. Los clientes reintentan solo tras una recodificación segura. Los nuevos tipos se despliegan a través de una matriz de compatibilidad y métricas para que las pasarelas o SDKs antiguos no cambien la semántica silenciosamente.”
Errores comunes
- Usar Accept para clasificar el cuerpo de la solicitud → se mezclan la negociación de solicitud y respuesta → inspecciona Content-Type y Content-Encoding.
- Devolver 415 para cada fallo de análisis sintáctico → los clientes no pueden elegir una reparación → separa errores de medios, de sintaxis y de dominio.
- Anunciar Accept-Patch sin un analizador correspondiente → el contrato de capacidad es falso → valida la declaración frente a la implementación.
- Reintentar el mismo cuerpo tras un 415 → fallará o duplicará efectos secundarios → cambia la codificación y confirma la seguridad de repetición.
- Registrar el tipo solo en la aplicación → las reescrituras de la pasarela se vuelven invisibles → compara encabezados e IDs de solicitud por cada salto (hop).
Preguntas de seguimiento y respuestas
Si Content-Type es válido pero Content-Encoding no es compatible, ¿sigue siendo correcto devolver 415?
El RFC 9110 incluye una codificación de contenido de solicitud inaceptable dentro del alcance de 415. Explica la codificación en el error, luego descomprime o selecciona una codificación soportada antes de decidir si el cuerpo y la operación se pueden reintentar de forma segura.
¿Por qué no devolver solo una lista de tipos permitidos?
Una lista omite restricciones de método, parámetros y versión. Un código estable, el valor recibido, el alcance permitido, el ID de solicitud y un enlace a la documentación hacen que la corrección sea procesable sin exponer detalles internos.
¿Cómo agregar CBOR de manera segura?
Habilítalo primero en recursos no críticos, verifica el paso a través de la pasarela, los límites de recursos del analizador, la equivalencia de esquema y la ofuscación de logs. Mantén la alternativa (fallback) a JSON y compara los 415, los fallos de análisis y los resultados de negocio según la versión del cliente.