El método HTTP QUERY para los equipos front-end: lecturas seguras con cuerpo de solicitud

Las pantallas de búsqueda y filtrado presentan un problema recurrente en la API. Al codificar cada filtro en una cadena de consulta GET, la URL se vuelve larga y poco práctica; si se envían los filtros como JSON mediante POST, se está utilizando un método que indica un cambio de estado cuando en realidad se trata de una operación de lectura. El método HTTP QUERY está diseñado precisamente para resolver esta situación. Este artículo explica qué significa QUERY, cómo enviarlo desde una aplicación React con fetch, y qué partes de tu stack, desde CORS hasta los cachés, requieren atención antes de poder confiar en él.

El problema que resuelve QUERY

Una lista de productos con unos pocos filtros genera rápidamente una solicitud como esta:

/products?category=laptop&brand=Apple&minPrice=50000&maxPrice=150000&rating=4

Funciona, pero cada nuevo filtro alarga la cadena; los valores anidados o repetidos (varias marcas, rango de precios, orden de clasificación, paginación) necesitan convenios de codificación específicos, y las URLs muy largas pueden superar los límites de longitud en servidores, proxies y registros.

La solución habitual es utilizar POST con un cuerpo en formato JSON. Esto resulta más sencillo de implementar en el cliente, pero complica el contrato de comunicación. POST no es ni seguro ni idempotente, por lo que los intermediarios no pueden asumir que la solicitud es inocua para ser repetida, los cachés por defecto no almacenarán la respuesta, y cualquiera que consulte la API debe revisar la documentación para saber que este POST en particular solo sirve para leer datos.

Qué es QUERY

QUERY es un método HTTP para solicitar a un servidor que ejecute una consulta descrita en el contenido de la solicitud. Según los informes al momento de redactar este texto, el IETF lo publicó como estándar en junio de 2026 bajo la designación RFC 10008; consulte el índice de RFCs para conocer su estado actual antes de citarlo. En lugar de incluir los parámetros en la URL, el cliente los envía en el cuerpo de la solicitud:

QUERY /products HTTP/1.1
Content-Type: application/json

{
  "category": "laptop",
  "brands": ["Apple", "Dell"],
  "price": {
    "min": 50000,
    "max": 150000
  }
}

El servidor evalúa la consulta y devuelve los resultados correspondientes. Lo que distingue a QUERY de POST es su semántica: se define como seguro, lo que significa que no modifica el recurso objetivo, y idempotente, lo que implica que enviarla dos veces tiene el mismo efecto que enviarla una vez. Esas dos propiedades son las que permiten a los clientes, proxies y cachés tratarla como una operación de lectura. La idempotencia, por ejemplo, significa que un cliente o intermediario puede volver a intentar una QUERY fallida automáticamente sin arriesgarse a efectos secundarios duplicados, algo que no debería hacer con POST.

Elegir entre GET, POST y QUERY

QUERY no reemplaza a los otros métodos. Cada uno sigue teniendo un papel claro:

• GET sigue siendo el método por defecto para recuperaciones sencillas: un recurso por ID, una lista corta con pocos parámetros simples.

POST sigue siendo el método para operaciones que crean o modifican el estado del servidor, o aquellas que no son seguras para repetirse.

QUERY es adecuado para lecturas cuya entrada es lo suficientemente compleja como para requerir contenido estructurado, como filtros anidados, arrays de valores o expresiones de consulta.

Para el frontend, la ventaja radica en que los mapas de estado de filtros complejos se corresponden directamente con el cuerpo de la solicitud, y el contrato de la API indica claramente que no se está modificando nada.

Envío de una solicitud QUERY desde React

Imaginemos un componente de React que almacena sus filtros actuales del producto en un objeto:

const filters = {
  category: "laptop",
  brands: ["Apple", "Dell"],
  price: {
    min: 50000,
    max: 150000
  },
  rating: 4
};

Con QUERY, ese objeto puede ser serializado y enviado tal como está. La función auxiliar a continuación utiliza fetch con un nombre de método personalizado y un cuerpo en JSON:

const searchProducts = async (filters) => {
  const response = await fetch("/api/products", {
    method: "QUERY",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify(filters)
  });

La segunda mitad de la misma función verifica el estado de respuesta y analiza el resultado:

  if (!response.ok) {
    throw new Error("Failed to fetch products");
  }  return response.json();
};

Aparte de la cadena del método, esto es idéntico a una llamada POST. El cambio es semántico y no sintáctico: la solicitud ahora se declara como una consulta. Hay dos detalles prácticos a tener en cuenta. El estándar Fetch solo escribe en mayúsculas algunos nombres de métodos bien conocidos, por lo que siempre se debe escribir "QUERY" en mayúsculas. Además, a diferencia de GET y HEAD, que fetch se niega a enviar con un cuerpo, QUERY permite llevar uno.

Hay un compromiso específico en las interfaces de usuario. Los filtros codificados en la URL son guardables como marcadores y compartibles, y sobreviven a la recarga de la página. Un cuerpo QUERY no lo hace. Si los enlaces compartibles son importantes, es posible que aún quiera reflejar el estado del filtro en la URL de la página en el cliente, mientras se envía la consulta estructurada a la API.

Verificar el soporte en todo el camino de la solicitud

El hecho de que un método esté siendo estandarizado no implica que todos los componentes que manejan su tráfico lo comprendan. Una solicitud del navegador pasa por varias capas antes de llegar a la aplicación, y cualquiera de ellas puede rechazar o alterar un método desconocido. Antes de implementar QUERY, verifique:

• El comportamiento del navegador y de fetch() en los navegadores que soporta.
• La configuración CORS de la API.
• Las pasarelas de API y los proxies inversos.
• Los CDN y las cachés periféricas.
• El middleware de autenticación y autorización.
• Las herramientas de monitoreo, registro y trazado.
• El enrutamiento y el análisis del cuerpo de las solicitudes del framework backend.

Algunas capas pueden permitir solo una lista fija de métodos, y otras pueden descartar el cuerpo de las solicitudes que no reconozcan. Pruebe el proceso de extremo a extremo en un entorno similar al de producción, y no solo contra un servidor local.

CORS siempre requiere una solicitud de preflight

QUERY no está entre los métodos permitidos por CORS (GET, HEAD y POST). Eso significa que una solicitud QUERY de origen cruzado desde el navegador siempre activa una solicitud de preflight: antes de la solicitud real, el navegador envía una solicitud OPTIONS para preguntar si se permite QUERY.

Si tu aplicación React y la API están en orígenes diferentes, el servidor debe responder a esa solicitud de preflight con un encabezado Access-Control-Allow-Methods que incluya a QUERY, junto con cualquier otro encabezado que utilice tu solicitud, como Content-Type. Un cuerpo JSON también obliga a realizar una solicitud de preflight para POST, por lo que el costo adicional suele ser mínimo, pero el método debe estar listado explícitamente.

Esto es fácil de pasar por alto durante el desarrollo. Herramientas como Postman y curl no aplican las reglas de CORS, por lo que un endpoint puede funcionar perfectamente allí y fallar en el navegador.

El caché es posible, pero más complejo

Las respuestas de QUERY son cachable, lo cual es una de las principales ventajas de este método frente a POST. La complicación radica en que la respuesta depende del cuerpo de la solicitud, no solo de la URL. Considere estos dos cuerpos de solicitud enviados al mismo endpoint:

{
  "brand": "Apple"
}

{
  "brand": "Dell"
}

Deben devolver resultados diferentes. Por lo tanto, el caché debe incluir el contenido de la solicitud, y generalmente su tipo de medio, en la clave del caché al decidir si se puede reutilizar una respuesta almacenada. Los cachés también pueden normalizar el contenido (por ejemplo, ignorando espacios en blanco insignificantes en JSON) para que las consultas equivalentes compartan una misma entrada.

Para los desarrolladores de React y Next.js, la lección es no tratar a QUERY como “GET con cuerpo” en lo que respecta al cacheo. Los cachés HTTP del navegador, las CDN y los cachés de fetch a nivel de framework podrían no utilizar aún los cuerpos de solicitud como clave, así que es necesario confirmar cómo se comporta cada capa en lugar de asumir que habrá coincidencias en el caché.

Cómo se relaciona QUERY con GraphQL

GraphQL suele mencionarse en las mismas conversaciones, pero ambos operan en niveles diferentes. GraphQL te proporciona un lenguaje para describir los datos que deseas y un modelo para resolverlos. QUERY es solo un verbo a nivel de transporte: especifica cómo debe tratarse una solicitud que contiene contenido de consulta mediante HTTP. Actualmente, los clientes GraphQL suelen enviar operaciones con POST; en principio, un servidor GraphQL podría aceptar operaciones de lectura a través de QUERY, pero QUERY no reemplaza a GraphQL, y ambos pueden coexistir según el diseño de la API.

¿Deberías migrar las APIs existentes?

Por lo general, no, al menos no solo porque existe QUERY. Si un punto de extremo de búsqueda ya funciona bien con GET o POST, cambiarlo implica trabajo adicional de migración y compatibilidad con beneficios limitados. QUERY tiene más sentido al diseñar un nuevo punto de extremo cuyas solicitudes sean:

• Solo de lectura.

Potencialmente complejo.

Se expresa de manera más natural como contenido estructurado que como parámetros de URL.

Probablemente se beneficie de semánticas seguras e idempotentes, como las reintentos y el caché.

Ofrece a los equipos una alternativa fundamentada en lugar de recurrir siempre a POST cuando una solicitud GET se vuelve inviable.

Puntos clave

• Use GET para recuperaciones simples y mantenga las llamadas sencillas tal como son.
• Considere QUERY para solicitudes complejas de solo lectura que requieren un cuerpo estructurado.
• No espere una mayor velocidad: QUERY cambia la forma en que se representa la solicitud, no la rapidez del backend o de la red.
• Verifique el soporte en navegadores, proxies, gateways, CDNs y su framework backend antes de usarlo en producción.
• Configure CORS para permitir explícitamente el método y pruébelo en un navegador real.
• Confirme que todas las claves de la capa de caché en el cuerpo de la solicitud estén correctas antes de confiar en las respuestas QUERY almacenadas en caché.
• Preste atención a la adopción en el ecosistema: las páginas de búsqueda, los paneles de control y las aplicaciones con grandes volúmenes de datos son donde QUERY probablemente dará sus primeros frutos.